Team structure knowledge and health analysis commands for OpenShift teams

version
0.0.18
GitHub stars
123

Install

/plugin install teams@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

Analyze Regressions

This skill provides functionality to analyze and grade component health for OpenShift releases based on regression management metrics. It evaluates how well components are managing their test regressions by analyzing triage coverage, triage timeliness, and resolution speed.

When to Use This Skill

Use this skill when you need to:

  • Grade component health for a specific OpenShift release
  • Identify components that need help with regression handling
  • Track triage and resolution efficiency across releases
  • Generate component quality scorecards
  • Produce health reports (text or HTML) for stakeholders

Important Note: Grading is subjective and not meant to be a critique of team performance. This is intended to help identify where help is needed and track progress as we improve our regression response rates.

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. Network Access

    • The scripts require network access to reach the component health API and release dates API
    • Ensure you can make HTTPS requests
  3. Required Scripts

    • plugins/teams/skills/get-release-dates/get_release_dates.py
    • plugins/teams/skills/list-regressions/list_regressions.py
    • plugins/teams/skills/analyze-regressions/generate_html_report.py (for HTML reports)
    • plugins/teams/skills/analyze-regressions/report_template.html (for HTML reports)

Implementation Steps

Step 1: Parse Arguments

Extract the view name and optional component filter from the command arguments:

  • View format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
  • The release is derived from the view name (e.g., "4.22" from "4.22-main")
  • Components (optional): List of component names to filter by

Example argument parsing:

/teams:analyze-regressions 4.17-main
/teams:analyze-regressions 4.21-main --components Monitoring etcd

Step 2: Fetch Release Dates

Derive the release from the view name (e.g., "4.17" from "4.17-main"), then run the get_release_dates.py script to determine the development window:

python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 4.17

Expected output (JSON on stdout):

{
  "release": "4.17",
  "development_start": "2024-05-17T00:00:00Z",
  "feature_freeze": "2024-08-26T00:00:00Z",
  "code_freeze": "2024-09-30T00:00:00Z",
  "ga": "2024-10-29T00:00:00Z"
}

Processing steps:

  1. Parse the JSON output
  2. Extract development_start date - convert to YYYY-MM-DD format
  3. Extract ga date - convert to YYYY-MM-DD format (may be null for in-development releases)
  4. Handle null dates as follows:
    • development_start: Usually always present; if null, omit --start parameter
    • ga: Will be null for in-development releases; if null, omit --end parameter

Date conversion example:

"2024-05-17T00:00:00Z" → "2024-05-17"
null → do not use this parameter

Step 3: Execute List Regressions Script

Run the list_regressions.py script with the appropriate arguments:

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main \
  --start 2024-05-17 \
  --end 2024-10-29 \
  --short

Parameter rules:

  • --view: Always required (from Step 1). The release is derived from the view name internally.
  • --components: Optional, only if specified by user (from Step 1)
  • --start: Use development_start date from Step 2 (if not null)
    • Always applied for both GA'd and in-development releases
    • Excludes regressions closed before development started (not relevant to this release)
  • --end: Use ga date from Step 2 (only if not null)
    • Only applied for GA'd releases (when GA date is not null)
    • Excludes regressions opened after GA (post-release regressions, often not monitored/triaged)
    • Not applied for in-development releases (when GA date is null)
  • --short: Always include this flag
    • Excludes regression data arrays from response
    • Only includes summary statistics
    • Prevents truncation problems with large datasets

Example for GA'd release (4.17-main):

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main \
  --start 2024-05-17 \
  --end 2024-10-29 \
  --short

Example for in-development release (4.22-main with null GA):

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.22-main \
  --start 2025-09-02 \
  --short

Example with component filter:

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.21-main \
  --components Monitoring etcd \
  --start 2025-09-02 \
  --short

Step 4: Parse Output Structure

The script outputs JSON to stdout with the following structure:

{
  "summary": {
    "total": 62,
    "triaged": 59,
    "triage_percentage": 95.2,
    "filtered_suspected_infra_regressions": 8,
    "time_to_triage_hrs_avg": 68,
    "time_to_triage_hrs_max": 240,
    "time_to_resolve_hrs_avg": 168,
    "time_to_resolve_hrs_max": 480,
    "open": {
      "total": 2,
      "triaged": 1,
      "triage_percentage": 50.0,
      "time_to_triage_hrs_avg": 48,
      "time_to_triage_hrs_max": 48,
      "open_hrs_avg": 120,
      "open_hrs_max": 200
    },
    "closed": {
      "total": 60,
      "triaged": 58,
      "triage_percentage": 96.7,
      "time_to_triage_hrs_avg": 72,
      "time_to_triage_hrs_max": 240,
      "time_to_resolve_hrs_avg": 168,
      "time_to_resolve_hrs_max": 480
    }
  },
  "components": {
    "ComponentName": {
      "summary": {
        "total": 15,
        "triaged": 13,
        "triage_percentage": 86.7,
        "filtered_suspected_infra_regressions": 0,
        "time_to_triage_hrs_avg": 68,
        "time_to_triage_hrs_max": 180,
        "time_to_resolve_hrs_avg": 156,
        "time_to_resolve_hrs_max": 360,
        "open": {
          "total": 1,
          "triaged": 0,
          "triage_percentage": 0.0,
          "time_to_triage_hrs_avg": null,
          "time_to_triage_hrs_max": null,
          "open_hrs_avg": 72,
          "open_hrs_max": 72
        },
        "closed": {
          "total": 14,
          "triaged": 13,
          "triage_percentage": 92.9,
          "time_to_triage_hrs_avg": 68,
          "time_to_triage_hrs_max": 180,
          "time_to_resolve_hrs_avg": 156,
          "time_to_resolve_hrs_max": 360
        }
      }
    }
  }
}

CRITICAL - Use Summary Counts:

  • ALWAYS use summary.total, summary.open.total, summary.closed.total for counts
  • ALWAYS use components.*.summary.* for per-component counts
  • Do NOT attempt to count regression arrays (they are excluded with --short flag)
  • This ensures accuracy even with large datasets

Key Metrics to Extract:

From summary object:

  • summary.total - Total regressions
  • summary.triaged - Total triaged regressions
  • summary.triage_percentage - KEY HEALTH METRIC: Percentage triaged
  • summary.filtered_suspected_infra_regressions - Count of filtered infrastructure regressions
  • summary.time_to_triage_hrs_avg - KEY HEALTH METRIC: Average hours to triage
  • summary.time_to_triage_hrs_max - Maximum hours to triage
  • summary.time_to_resolve_hrs_avg - KEY HEALTH METRIC: Average hours to resolve (regression opened to triage resolved)
  • summary.time_to_resolve_hrs_max - Maximum hours to resolve
  • summary.open.total - Open regressions count
  • summary.open.triaged - Open triaged count
  • summary.open.triage_percentage - Open triage percentage
  • summary.closed.total - Closed regressions count
  • summary.closed.triaged - Closed triaged count
  • summary.closed.triage_percentage - Closed triage percentage

From components object:

  • Same fields as summary, but per-component
  • Use components.*.summary.* for all per-component statistics

Step 5: Calculate Health Grades

IMPORTANT - Closed Regression Triage:

  • DO NOT recommend retroactively triaging closed regressions - the tooling does not support this
  • When identifying untriaged regressions that need attention, only consider open regressions: summary.open.total - summary.open.triaged
  • Closed regression triage percentages are provided for historical analysis only, not as actionable items
Overall Health Grade

Calculate grades based on three key metrics:

1. Triage Coverage (summary.triage_percentage):

  • 90-100%: Excellent ✅
  • 70-89%: Good ⚠️
  • 50-69%: Needs Improvement ⚠️
  • <50%: Poor ❌

2. Triage Timeliness (summary.time_to_triage_hrs_avg):

  • <24 hours: Excellent ✅
  • 24-72 hours: Good ⚠️
  • 72-168 hours (1 week): Needs Improvement ⚠️
  • 168 hours: Poor ❌

3. Resolution Speed (summary.time_to_resolve_hrs_avg):

  • <168 hours (1 week): Excellent ✅
  • 168-336 hours (1-2 weeks): Good ⚠️
  • 336-720 hours (2-4 weeks): Needs Improvement ⚠️
  • 720 hours (4+ weeks): Poor ❌

Per-Component Health Grades

For each component in components:

  1. Calculate the same three grades using components.*.summary.* fields
  2. Rank components from best to worst health
  3. Highlight components needing attention:
    • Low triage coverage (<50%)
    • Slow triage response (>72 hours average)
    • Slow resolution time (>336 hours / 2 weeks average)
    • High open regression counts
    • High overall regression counts

Step 6: Display Text Report

Present a well-formatted text report with:

Overall Health Grade Section

Display overall statistics from summary:

=== Overall Health Grade for Release 4.17 ===
Development Window: 2024-05-17 to 2024-10-29 (GA'd release)

Total Regressions: 62
Filtered Infrastructure Regressions: 8
Triaged: 59 (95.2%)
Open: 2 (50.0% triaged)
Closed: 60 (96.7% triaged)

Triage Coverage: ✅ Excellent (95.2%)
Triage Timeliness: ⚠️ Good (68 hours average, 240 hours max)
Resolution Speed: ✅ Excellent (168 hours average, 480 hours max)

Important: If the GA date is null (in-development release), note:

Development Window: 2025-09-02 onwards (In Development)
Per-Component Health Scorecard

Display ranked table from components.*.summary:

=== Component Health Scorecard ===

| Component       | Triage Coverage | Triage Time | Resolution Time | Open | Grade |
|-----------------|-----------------|-------------|-----------------|------|-------|
| kube-apiserver  | 100.0%          | 58 hrs      | 144 hrs         | 1    | ✅    |
| etcd            | 95.0%           | 84 hrs      | 192 hrs         | 0    | ✅    |
| Monitoring      | 86.7%           | 68 hrs      | 156 hrs         | 1    | ⚠️    |
Components Needing Attention

Highlight specific components with issues:

=== Components Needing Attention ===

Monitoring:
  - 1 open untriaged regression (needs triage)
  - Triage coverage: 86.7% (below 90%)

Example-Component:
  - 5 open untriaged regressions (needs triage)
  - Slow triage response: 120 hours average
  - High open count: 5 open regressions

CRITICAL: When listing untriaged regressions that need action:

  • Only list OPEN untriaged regressions - these are actionable
  • Do NOT recommend triaging closed regressions - the tooling does not support retroactive triage
  • Calculate actionable untriaged count as: components.*.summary.open.total - components.*.summary.open.triaged

Step 7: Offer HTML Report Generation

After displaying the text report, ask the user if they want an interactive HTML report:

Would you like me to generate an interactive HTML report? (yes/no)

If the user responds affirmatively:

Step 7a: Prepare Data for HTML Report

The HTML report requires data in a specific structure. Transform the JSON data:

# Prepare component data for HTML template
component_data = []
for component_name, component_obj in components.items():
    summary = component_obj['summary']
    component_data.append({
        'name': component_name,
        'total': summary['total'],
        'open': summary['open']['total'],
        'closed': summary['closed']['total'],
        'triaged': summary['triaged'],
        'triage_percentage': summary['triage_percentage'],
        'time_to_triage_hrs_avg': summary.get('time_to_triage_hrs_avg'),
        'time_to_resolve_hrs_avg': summary.get('time_to_resolve_hrs_avg'),
        'health_grade': calculate_health_grade(summary)  # Calculate combined grade
    })
Step 7b: Generate HTML Report

Use the generate_html_report.py script (or inline Python code):

python3 plugins/teams/skills/analyze-regressions/generate_html_report.py \
  --release 4.17 \
  --data regression_data.json \
  --output .work/teams-4.17/report.html

Or use inline Python with the template:

import json
from datetime import datetime

# Load template
with open('plugins/teams/skills/analyze-regressions/report_template.html', 'r') as f:
    template = f.read()

# Replace placeholders
template = template.replace('{{RELEASE}}', '4.17')
template = template.replace('{{GENERATED_DATE}}', datetime.now().isoformat())
template = template.replace('{{SUMMARY_DATA}}', json.dumps(summary))
template = template.replace('{{COMPONENT_DATA}}', json.dumps(component_data))

# Write output
output_path = '.work/teams-4.17/report.html'
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, 'w') as f:
    f.write(template)
Step 7c: Open the Report

Open the HTML report in the user's default browser:

macOS:

open .work/teams-4.17/report.html

Linux:

xdg-open .work/teams-4.17/report.html

Windows:

start .work/teams-4.17/report.html

Display the file path to the user:

HTML report generated: .work/teams-4.17/report.html
Opening in your default browser...

Error Handling

Common Errors

  1. Network Errors

    • Symptom: URLError or connection timeout
    • Solution: Check network connectivity and firewall rules
    • Retry: Both scripts have 30-second timeouts
  2. Invalid Release Format

    • Symptom: Empty results or error response
    • Solution: Verify the view format (e.g., "4.17-main", not "4.17" or "v4.17")
  3. Release Dates Not Found

    • Symptom: get_release_dates.py returns error
    • Solution: Verify the release exists in the system; may be too old or not yet created
    • Fallback: Proceed without date filtering (omit --start and --end parameters)
  4. No Regressions Found

    • Symptom: Empty components object
    • Solution: Verify the release has regression data; may be too early in development
    • Action: Inform user that no regressions exist yet for this release
  5. Component Filter No Matches

    • Symptom: Empty components object after filtering
    • Solution: Check component name spelling; component names are case-insensitive
    • Action: List available components from unfiltered query
  6. HTML Template Not Found

    • Symptom: FileNotFoundError when generating HTML report
    • Solution: Verify template exists at plugins/teams/skills/analyze-regressions/report_template.html
    • Fallback: Offer text report only

Debugging

Enable verbose output by examining stderr:

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main \
  --short 2>&1 | tee debug.log

Diagnostic messages include:

  • URL being queried
  • Number of regressions fetched
  • Number after filtering
  • Number of suspected infrastructure regressions filtered

Output Format

Text Report Structure

The text report should include:

  1. Header

    • Release version
    • Development window dates (start and end/GA)
    • Release status (GA'd or In Development)
  2. Overall Health Grade

    • Total regressions
    • Filtered infrastructure regressions count
    • Open/closed breakdown
    • Triage coverage score with grade
    • Triage timeliness score with grade
    • Resolution speed score with grade
  3. Component Health Scorecard

    • Ranked table of all components
    • Key metrics per component
    • Health grade per component
  4. Components Needing Attention

    • List of components with specific issues
    • Actionable recommendations (only for open untriaged regressions)
    • Context for each issue
  5. Footer

    • Link to Sippy dashboard (if applicable)
    • Timestamp of report generation

HTML Report Features

The HTML report should include:

  • Interactive table with sorting and filtering
  • Visual indicators for health grades (colors, icons)
  • Charts/graphs showing:
    • Triage coverage by component
    • Time to triage distribution
    • Open vs closed breakdown
  • Detailed metrics on hover or click
  • Export functionality (CSV, PDF)
  • Responsive design for mobile viewing

Examples

Example 1: Grade Overall Release Health

/teams:analyze-regressions 4.17-main

Execution flow:

  1. Derive release "4.17" from view "4.17-main"
  2. Fetch release dates for 4.17
  3. Run list_regressions.py with --view 4.17-main --start and --end (GA'd release)
  4. Display overall health grade
  5. Display per-component scorecard
  6. Highlight components needing attention
  7. Offer HTML report generation

Example 2: Grade Specific Components

/teams:analyze-regressions 4.22-main --components Monitoring etcd

Execution flow:

  1. Derive release "4.22" from view "4.22-main"
  2. Fetch release dates for 4.22 (may have null GA)
  3. Run list_regressions.py with --view --components and --start only (in-development)
  4. Display health grades for Monitoring and etcd only
  5. Compare the two components
  6. Identify which needs more attention

Example 3: Grade Single Component

/teams:analyze-regressions 4.21-main --components "kube-apiserver"

Execution flow:

  1. Derive release "4.21" from view "4.21-main"
  2. Fetch release dates for 4.21
  3. Run list_regressions.py with --view and single component filter
  4. Display detailed health metrics for kube-apiserver
  5. Show open vs closed breakdown
  6. List count of open untriaged regressions (if any)

Health Grade Calculation Details

Combined Health Grade

To calculate an overall health grade for a component, consider all three metrics:

def calculate_health_grade(summary):
    """Calculate combined health grade based on three key metrics."""
    triage_coverage = summary['triage_percentage']
    triage_time = summary.get('time_to_triage_hrs_avg')
    resolution_time = summary.get('time_to_resolve_hrs_avg')

    # Score each metric (0-3)
    coverage_score = (
        3 if triage_coverage >= 90 else
        2 if triage_coverage >= 70 else
        1 if triage_coverage >= 50 else
        0
    )

    time_score = 3  # Default to excellent if no data
    if triage_time is not None:
        time_score = (
            3 if triage_time < 24 else
            2 if triage_time < 72 else
            1 if triage_time < 168 else
            0
        )

    resolution_score = 3  # Default to excellent if no data
    if resolution_time is not None:
        resolution_score = (
            3 if resolution_time < 168 else
            2 if resolution_time < 336 else
            1 if resolution_time < 720 else
            0
        )

    # Average the scores
    avg_score = (coverage_score + time_score + resolution_score) / 3

    # Return grade
    if avg_score >= 2.5:
        return "Excellent ✅"
    elif avg_score >= 1.5:
        return "Good ⚠️"
    elif avg_score >= 0.5:
        return "Needs Improvement ⚠️"
    else:
        return "Poor ❌"

Prioritizing Components Needing Attention

Rank components by priority based on:

  1. High open untriaged count (most urgent)

    • Calculate: summary.open.total - summary.open.triaged
    • Threshold: >3 open untriaged regressions
  2. Low triage coverage (second priority)

    • Use: summary.triage_percentage
    • Threshold: <50%
  3. Slow triage response (third priority)

    • Use: summary.time_to_triage_hrs_avg
    • Threshold: >72 hours
  4. High total regression count (fourth priority)

    • Use: summary.total
    • Threshold: Component-relative (top quartile)

Advanced Features

Trend Analysis (Future Enhancement)

Compare metrics across releases:

/teams:analyze-regressions 4.17 --compare 4.16

Export to CSV

Generate CSV report for spreadsheet analysis:

/teams:analyze-regressions 4.17 --export-csv

Custom Thresholds

Allow users to customize health grade thresholds:

/teams:analyze-regressions 4.17 --triage-threshold 80

Integration with Other Commands

This skill can be used by:

  • /teams:analyze-regressions command (primary)
  • Quality metrics dashboards
  • Release readiness reports
  • Team performance tracking tools

Related Skills

  • get-release-dates - Fetches release development window dates
  • list-regressions - Fetches raw regression data
  • ci:prow-job-analysis - Comprehensive Prow CI job failure analysis

Notes

  • All scripts use Python's standard library only (no external dependencies)
  • Output is cached in .work/ directory for performance
  • Regression data is fetched in real-time from the API
  • HTML reports are standalone (no external dependencies, embedded CSS/JS)
  • The --short flag is critical to prevent output truncation with large datasets
  • Health grades are subjective and intended as guidance, not criticism
  • Infrastructure regressions (closed within 96 hours on high-volume days) are automatically filtered
  • Retroactive triage of closed regressions is not supported by the tooling

Troubleshooting

Issue: Report Shows 0 Regressions

Possible causes:

  1. Release is too early in development
  2. Date filtering excluded all regressions
  3. Component filter didn't match any components

Solutions:

  1. Check release dates with get_release_dates.py
  2. Try without date filtering
  3. List available components without filter first

Issue: Triage Percentages Seem Low

Context:

  • Many teams are still ramping up regression triage practices
  • Low percentages indicate opportunity for improvement, not failure
  • Focus on the trend over time rather than absolute numbers

Actions:

  • Identify specific untriaged open regressions that need attention
  • Prioritize by regression severity and frequency
  • Track improvement over subsequent releases

Issue: HTML Report Not Opening

Possible causes:

  1. Browser security restrictions on local files
  2. Incorrect file path
  3. Missing file permissions

Solutions:

  1. Manually open the file from file explorer
  2. Verify the file was created at the expected path
  3. Check file permissions: ls -la .work/teams-*/report.html

Summary

This skill provides comprehensive component health analysis by:

  1. Fetching release development window dates
  2. Retrieving regression data filtered to the development window
  3. Calculating health grades based on triage metrics
  4. Generating actionable reports (text and HTML)
  5. Identifying components that need help

The key focus is on actionable insights - particularly identifying open untriaged regressions that need immediate attention, while avoiding recommendations for closed regressions which cannot be retroactively triaged.

CodeRabbit Adoption Report

This skill queries the GitHub search API to measure what percentage of merged PRs in the openshift GitHub organization received comments from the coderabbitai[bot] app.

When to Use This Skill

Use this skill when you need to:

  • Measure CodeRabbit adoption rates across the openshift org
  • Identify repos with high or low CodeRabbit usage
  • Generate adoption reports for stakeholders
  • Track adoption trends over time

Prerequisites

  1. GitHub CLI (gh): Must be installed and authenticated with access to the openshift org.

    gh auth status
    
  2. Python 3: Python 3.6 or later is required.

Implementation Steps

Step 1: Verify Prerequisites

gh auth status
python3 --version

Step 2: Run the Script

The script is located at:

plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py

Execute with appropriate arguments:

# Default: last 30 days, org-wide summary only (2 API calls)
python3 plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py

# Specific date range
python3 plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py \
  --start-date 2026-02-01 --end-date 2026-02-28

# Detailed mode: per-repo breakdowns (~50 API calls, prone to rate limiting)
# ONLY use when user explicitly requests --detailed
python3 plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py --detailed

Step 3: Parse the Output

The script outputs JSON to stdout with the following structure:

Default mode (2 API calls, no per-repo data):

{
  "start_date": "2026-02-04",
  "end_date": "2026-03-06",
  "total_merged_prs": 7950,
  "prs_with_coderabbit": 1445,
  "adoption_pct": 18.2,
  "detailed": false,
  "repo_breakdown": [],
  "no_coderabbit_activity": []
}

Detailed mode (~50 API calls, with per-repo data):

{
  "start_date": "2026-02-04",
  "end_date": "2026-03-06",
  "total_merged_prs": 7950,
  "prs_with_coderabbit": 1445,
  "adoption_pct": 18.2,
  "detailed": true,
  "per_repo_approximate": true,
  "repo_breakdown": [
    {
      "repo": "openshift/cincinnati-graph-data",
      "cr_count": 150,
      "total": 196,
      "adoption_pct": 76.5
    }
  ],
  "no_coderabbit_activity": [
    {
      "repo": "openshift/release",
      "total": 1072
    }
  ]
}

Field Descriptions:

  • start_date, end_date: The date range queried
  • total_merged_prs: Total merged PRs in the openshift org
  • prs_with_coderabbit: PRs where coderabbitai[bot] commented
  • adoption_pct: Overall adoption percentage
  • detailed: Whether detailed mode was used
  • per_repo_approximate: (detailed only) True if per-repo breakdown is approximate (>1000 CodeRabbit PRs)
  • repo_breakdown: (detailed only) Array of top repos sorted by CR count descending
  • no_coderabbit_activity: (detailed only) High-volume repos with zero CodeRabbit comments

Step 4: Format and Present the Report

  • Default mode: Present the summary stats (total PRs, CodeRabbit PRs, adoption %)
  • Detailed mode: Also include per-repo table and no-activity list

Step 5: AI Analysis

After presenting the data, provide:

  • License gap analysis: repos in repo_breakdown are enabled; missing reviews = engineers without licenses
  • Observations on adoption trends
  • In default mode, mention --detailed is available but warn it is prone to GitHub API rate limits

Notes

  • API usage: Default mode uses only 2 API calls. --detailed makes ~50 calls with 2-second sleeps between each to respect GitHub's search API rate limit (30 requests/minute). Even with throttling, --detailed may hit rate limits and takes several minutes.
  • The script uses gh CLI with -X GET for all GitHub API calls (required for the search endpoint)
  • Uses Python's standard library only (no external dependencies)
  • Diagnostic messages go to stderr, JSON data to stdout
  • Never use --detailed unless the user explicitly asks for it

CodeRabbit Inheritance Scanner - Check

This skill checks a single repository's .coderabbit.yaml (or .coderabbit.yml) to determine whether inheritance: true is set.

When to Use This Skill

Use this skill as Step 2 of the /teams:coderabbit-inheritance-scanner command. Call it once per repo found by the search skill. Multiple repos can be checked in a single bash invocation using the batch procedure below.

Procedure

For a batch of repos stored in a bash array, run the following to classify each one:

# Input: REPOS array of "org/repo" strings
# Output: prints classification and default branch for each repo

for REPO in "${REPOS[@]}"; do
  CONTENT=""
  CFGFILE=""
  for FILENAME in .coderabbit.yaml .coderabbit.yml; do
    CONTENT=$(gh api "repos/${REPO}/contents/${FILENAME}" --jq '.content' 2>/dev/null | base64 -d 2>/dev/null)
    if [ -n "$CONTENT" ]; then
      CFGFILE="$FILENAME"
      break
    fi
  done

  # Get default branch for link generation
  DEFAULT_BRANCH=$(gh api "repos/${REPO}" --jq '.default_branch' 2>/dev/null)

  if [ -z "$CONTENT" ]; then
    echo "ERROR|${REPO}|${DEFAULT_BRANCH}|${CFGFILE}"
    continue
  fi

  if echo "$CONTENT" | grep -qE '^\s*inheritance:\s*true'; then
    echo "COMPLIANT|${REPO}|${DEFAULT_BRANCH}|${CFGFILE}"
  elif echo "$CONTENT" | grep -qE '^\s*inheritance:\s*false'; then
    echo "FALSE|${REPO}|${DEFAULT_BRANCH}|${CFGFILE}"
  else
    echo "MISSING|${REPO}|${DEFAULT_BRANCH}|${CFGFILE}"
  fi

  sleep 0.3
done

Output Format

Pipe-separated fields per line:

STATUS|org/repo|default_branch|config_filename

Where STATUS is one of:

  • COMPLIANT - inheritance: true is set
  • FALSE - inheritance: false is explicitly set
  • MISSING - the inheritance key is absent
  • ERROR - could not fetch the file

CodeRabbit Inheritance Scanner - Existing PR Check

This skill checks whether a repository already has an open pull request whose title contains "CodeRabbit inheritance" (case-insensitive substring match). Teams sometimes modify PR titles to satisfy merge requirements, so a substring match avoids missing renamed PRs. This prevents duplicate PRs from being opened.

When to Use This Skill

Use this skill as Step 3 of the /teams:coderabbit-inheritance-scanner command, after identifying non-compliant repos. Call it for each non-compliant repo.

Procedure

For a batch of non-compliant repos, check for existing PRs:

# Input: NON_COMPLIANT_REPOS array of "org/repo" strings
# Output: prints PR status for each repo

for REPO in "${NON_COMPLIANT_REPOS[@]}"; do
  # Search for open PRs whose title contains "CodeRabbit inheritance" (case-insensitive)
  PR_DATA=$(gh api "repos/${REPO}/pulls" \
    -f "state=open" \
    -f "per_page=100" \
    --jq '[.[] | select(.title | ascii_downcase | contains("coderabbit inheritance"))] | first? | {number: .number, html_url: .html_url, created_at: .created_at} // empty' 2>/dev/null)

  if [ -n "$PR_DATA" ]; then
    PR_NUMBER=$(echo "$PR_DATA" | jq -r '.number')
    PR_URL=$(echo "$PR_DATA" | jq -r '.html_url')
    CREATED_AT=$(echo "$PR_DATA" | jq -r '.created_at')

    # Calculate days open
    CREATED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CREATED_AT" "+%s" 2>/dev/null || date -d "$CREATED_AT" "+%s" 2>/dev/null)
    NOW_EPOCH=$(date "+%s")
    DAYS_OPEN=$(( (NOW_EPOCH - CREATED_EPOCH) / 86400 ))

    echo "HAS_PR|${REPO}|${PR_URL}|${DAYS_OPEN}"
  else
    echo "NO_PR|${REPO}||"
  fi

  sleep 0.3
done

Output Format

Pipe-separated fields per line:

STATUS|org/repo|pr_url|days_open

Where STATUS is one of:

  • HAS_PR - An open PR with the expected title was found
  • NO_PR - No matching open PR exists

Notes

  • Only checks for open PRs, not closed or merged ones. A previously merged PR means the repo may have become compliant (the check skill would have already classified it as COMPLIANT).
  • A previously closed (not merged) PR indicates the fix was rejected. The report should note this so the user can investigate before re-opening.
  • The days_open field helps prioritize follow-up on stale PRs.

CodeRabbit Inheritance Scanner - Open PR

This skill handles the complete workflow of opening a pull request to add inheritance: true to a repository's .coderabbit.yaml file. It always operates via a personal fork to avoid needing direct push access to upstream repos.

When to Use This Skill

Use this skill as Step 6 of the /teams:coderabbit-inheritance-scanner command, after the user has confirmed they want to open PRs. Call it once per non-compliant repo that does not already have an open fix PR.

Do NOT call this skill in --dry-run mode. Instead, display the actions that would be taken for each repo.

Prerequisites

  • gh CLI authenticated with repo scope
  • workflow scope is needed if the upstream repo contains GitHub Actions workflow files (for gh repo sync). If missing, the skill will skip the repo with a warning.

Procedure

For each repo that needs a fix PR, run the following. The variables REPO (e.g., openshift/api), DEFAULT_BRANCH (e.g., master or main), and CFGFILE (e.g., .coderabbit.yaml) must be set.

# Derive names
REPO_NAME="${REPO##*/}"
GH_USER=$(gh api user --jq '.login')
WORKDIR="/tmp/cr-fix-workdir/${REPO_NAME}"
BRANCH_NAME="add-coderabbit-inheritance"

echo "Processing: ${REPO}"

# Step 1: Fork the repo (idempotent - safe to call if fork exists)
gh repo fork "${REPO}" --clone=false 2>&1 || true
sleep 2

# Step 2: Sync the fork's default branch with upstream
SYNC_OUTPUT=$(gh repo sync "${GH_USER}/${REPO_NAME}" --source "${REPO}" --branch "${DEFAULT_BRANCH}" 2>&1)
SYNC_EXIT=$?
if [ $SYNC_EXIT -ne 0 ]; then
  if echo "$SYNC_OUTPUT" | grep -q "workflow"; then
    echo "SKIP|${REPO}|Fork sync failed: workflow scope required. Run: gh auth refresh -h github.com -s workflow"
    # Continue to next repo in the calling loop
    return 1 2>/dev/null || continue
  fi
  echo "SKIP|${REPO}|Fork sync failed: ${SYNC_OUTPUT}"
  return 1 2>/dev/null || continue
fi

# Step 3: Delete any stale branch from a previous run
gh api -X DELETE "repos/${GH_USER}/${REPO_NAME}/git/refs/heads/${BRANCH_NAME}" 2>/dev/null || true
sleep 1

# Step 4: Clone the fork and create the fix branch
rm -rf "${WORKDIR}"
if ! gh repo clone "${GH_USER}/${REPO_NAME}" "${WORKDIR}" -- -b "${DEFAULT_BRANCH}" --depth 1 2>&1; then
  echo "ERROR|${REPO}|Clone failed"
  return 1 2>/dev/null || continue
fi
cd "${WORKDIR}" || { echo "ERROR|${REPO}|cd into workdir failed"; return 1 2>/dev/null || continue; }
git checkout -b "${BRANCH_NAME}" 2>&1 || { echo "ERROR|${REPO}|Branch creation failed"; cd /tmp; return 1 2>/dev/null || continue; }

# Step 5: Add inheritance: true to the config file
if [ ! -f "${CFGFILE}" ]; then
  echo "ERROR|${REPO}|Config file ${CFGFILE} not found in cloned repo"
  cd /tmp
  return 1 2>/dev/null || continue
fi

if ! grep -qE '^\s*inheritance:\s*(true|false)\b' "${CFGFILE}"; then
  # Prepend inheritance: true as the first line
  printf 'inheritance: true\n' | cat - "${CFGFILE}" > "${CFGFILE}.tmp" && mv "${CFGFILE}.tmp" "${CFGFILE}"
else
  # Replace existing inheritance: false with true
  sed -i.bak 's/^\(\s*\)inheritance:\s*false/\1inheritance: true/' "${CFGFILE}" && rm -f "${CFGFILE}.bak"
fi

# Step 6: Commit and push
git add "${CFGFILE}"
git commit -m "$(cat <<'COMMITEOF'
Add inheritance: true to .coderabbit.yaml

Ensures this repo inherits the org-wide CodeRabbit review rules
defined in https://github.com/openshift/coderabbit
COMMITEOF
)" 2>&1

git push origin "${BRANCH_NAME}" 2>&1

# Step 7: Create the PR from fork to upstream
PR_URL=$(gh pr create \
  --repo "${REPO}" \
  --head "${GH_USER}:${BRANCH_NAME}" \
  --base "${DEFAULT_BRANCH}" \
  --title "Add CodeRabbit inheritance for org-wide rules" \
  --body "$(cat <<'BODYEOF'
Adds `inheritance: true` to `.coderabbit.yaml` so this repo inherits the org-wide review rules from [openshift/coderabbit](https://github.com/openshift/coderabbit).

Without this setting, the repo's custom `.coderabbit.yaml` overrides the org-level configuration entirely, meaning org-wide review instructions and path-based rules are not applied.
BODYEOF
)" 2>&1)

cd /tmp

if echo "$PR_URL" | grep -q "https://github.com"; then
  echo "OK|${REPO}|${PR_URL}"
else
  echo "ERROR|${REPO}|PR creation failed: ${PR_URL}"
fi

sleep 1

Output Format

Pipe-separated fields per line:

STATUS|org/repo|detail

Where STATUS is one of:

  • OK - PR created successfully; detail is the PR URL
  • SKIP - Repo was skipped; detail is the reason (e.g., missing workflow scope)
  • ERROR - An error occurred; detail is the error message

Dry Run Output

When --dry-run is active, do NOT execute this skill. Instead, for each repo that would get a PR, display:

[DRY RUN] openshift/<repo>:
  1. Fork openshift/<repo> (or use existing fork)
  2. Sync fork's <default_branch> with upstream
  3. Create branch: add-coderabbit-inheritance
  4. Prepend "inheritance: true" to <config_file>
  5. Push branch to fork
  6. Open PR: "Add CodeRabbit inheritance for org-wide rules"
     From: <user>:add-coderabbit-inheritance -> openshift/<repo>:<default_branch>

Notes

  • The fork operation is idempotent - gh repo fork will not fail if the fork already exists.
  • The stale branch deletion (Step 3) ensures a clean state if the command was previously run and the PR was closed without merging.
  • macOS sed -i requires a backup extension; the .bak file is cleaned up.
  • The WORKDIR under /tmp/cr-fix-workdir/ is cleaned up before each clone to ensure fresh state.

CodeRabbit Inheritance Scanner - Search

This skill searches the openshift GitHub organization for repositories containing .coderabbit.yaml or .coderabbit.yml files using the GitHub code search API.

When to Use This Skill

Use this skill as Step 1 of the /teams:coderabbit-inheritance-scanner command.

Procedure

Run the following bash script to search for repos. This uses GitHub code search to avoid iterating all ~800 repos individually.

ALL_REPOS=""

for FILENAME in .coderabbit.yaml .coderabbit.yml; do
  PAGE=1
  while true; do
    API_ERR=""
    RESULT=$(gh api -X GET "search/code" \
      -f "q=filename:${FILENAME} org:openshift" \
      -f "per_page=100" \
      -f "page=${PAGE}" \
      --jq '.items[] | .repository.full_name' 2> >(API_ERR=$(cat)))
    API_EXIT=$?
    if [ $API_EXIT -ne 0 ]; then
      echo "ERROR: GitHub code search API failed (exit ${API_EXIT}): ${API_ERR}" >&2
      echo "Check authentication with: gh auth status" >&2
      exit 1
    fi
    if [ -z "$RESULT" ]; then
      break
    fi
    ALL_REPOS="${ALL_REPOS}${RESULT}"$'\n'
    COUNT=$(echo "$RESULT" | wc -l | xargs)
    if [ "$COUNT" -lt 100 ]; then
      break
    fi
    PAGE=$((PAGE + 1))
    sleep 1
  done
  sleep 2
done

# Deduplicate, sort, exclude openshift/coderabbit
echo "$ALL_REPOS" | sort -u | grep -v '^$' | grep -v '^openshift/coderabbit$'

Output

A newline-separated list of org/repo names (e.g., openshift/api), excluding openshift/coderabbit.

Error Handling

If the code search API is unavailable or returns an error (e.g., due to authentication scope), inform the user that the search failed and suggest checking gh auth status.

CodeRabbit Rules from PR Reviews - Fetch Comments

This skill runs a Python script that fetches human review comments from recent merged PRs in a given GitHub repository. It handles all GitHub API calls, bot filtering, noise removal, rate limiting, and pagination, returning clean JSON output for AI analysis.

When to Use This Skill

Use this skill as Step 2-3 of the /teams:coderabbit-rules-from-pr-reviews command to collect review comments. The script replaces manual gh api calls with a single Python invocation.

Prerequisites

  1. GitHub CLI (gh): Must be installed and authenticated.
  2. Python 3: Python 3.6 or later.

Script Location

plugins/teams/skills/coderabbit-rules-from-pr-reviews/fetch_pr_comments.py

Usage

# Default: 30 most recent merged PRs
python3 plugins/teams/skills/coderabbit-rules-from-pr-reviews/fetch_pr_comments.py openshift/origin

# Custom count
python3 plugins/teams/skills/coderabbit-rules-from-pr-reviews/fetch_pr_comments.py openshift/origin --count 50

# Full URL
python3 plugins/teams/skills/coderabbit-rules-from-pr-reviews/fetch_pr_comments.py https://github.com/openshift/origin

What the Script Does

  1. Parses the repo argument — accepts owner/repo or full GitHub URL
  2. Fetches recent merged PRs via gh pr list
  3. For each PR, fetches two types of comments:
    • Inline code review comments (/pulls/{number}/comments)
    • General discussion comments (/issues/{number}/comments)
  4. Filters out noise:
    • Bot accounts: logins ending in [bot] or matching known bots (coderabbitai, openshift-ci, openshift-bot, openshift-merge-robot, codecov, dependabot, renovate, k8s-ci-robot, etc.)
    • Prow commands: comments where every line starts with /
    • Approvals: /lgtm, /approve, /hold, etc.
    • Short comments: less than 20 characters
  5. Rate limiting: 0.5s sleep between API calls, with retry logic for rate limit errors

Output Format

JSON to stdout, progress to stderr:

{
  "repo": "openshift/origin",
  "prs_analyzed": 30,
  "total_comments": 142,
  "unique_reviewers": 18,
  "reviewers": ["alice", "bob", "carol"],
  "prs": [
    {
      "number": 29500,
      "title": "Fix flaky test in e2e suite",
      "author": "dave",
      "url": "https://github.com/openshift/origin/pull/29500",
      "merged_at": "2026-03-25T14:30:00Z"
    }
  ],
  "comments": [
    {
      "pr": 29500,
      "user": "alice",
      "body": "This error should be wrapped with fmt.Errorf to preserve context",
      "path": "pkg/cmd/server/start.go",
      "type": "review",
      "pr_title": "Fix flaky test in e2e suite",
      "pr_author": "dave"
    },
    {
      "pr": 29500,
      "user": "bob",
      "body": "We should add a unit test for this edge case",
      "path": "",
      "type": "issue",
      "pr_title": "Fix flaky test in e2e suite",
      "pr_author": "dave"
    }
  ]
}

Field Descriptions

  • repo: The normalized owner/repo string
  • prs_analyzed: Number of merged PRs fetched
  • total_comments: Number of human review comments after filtering
  • unique_reviewers: Count of distinct human reviewers
  • reviewers: Sorted list of reviewer logins
  • prs[].number: PR number
  • prs[].title: PR title
  • prs[].author: PR author login
  • prs[].url: PR URL
  • prs[].merged_at: Merge timestamp
  • comments[].pr: PR number the comment belongs to
  • comments[].user: Reviewer login
  • comments[].body: Full comment text
  • comments[].path: File path (for inline review comments; empty for discussion comments)
  • comments[].type: "review" for inline code comments, "issue" for general discussion
  • comments[].pr_title: Title of the PR
  • comments[].pr_author: Author of the PR

Notes

  • Uses only Python standard library (no pip dependencies)
  • Diagnostic/progress messages go to stderr, JSON data to stdout
  • Handles GitHub API pagination for PRs with many comments
  • Retries on rate limits with exponential backoff
  • Analyzing 30 PRs typically takes 1-2 minutes (~60 API calls)

Get Release Dates

This skill provides functionality to fetch OpenShift release information including GA dates and development start dates from the Sippy API.

When to Use This Skill

Use this skill when you need to:

  • Get GA (General Availability) date for a specific OpenShift release
  • Find when development started for a release
  • Identify the previous release in the sequence
  • Validate if a release exists in Sippy
  • Determine if a release is in development or has GA'd

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. Network Access

    • The script requires network access to reach the Sippy API
    • Ensure you can make HTTPS requests to sippy.dptools.openshift.org

Implementation Steps

Step 1: Verify Prerequisites

First, ensure Python 3 is available:

python3 --version

If Python 3 is not installed, guide the user through installation for their platform.

Step 2: Locate the Script

The script is located at:

plugins/teams/skills/get-release-dates/get_release_dates.py

Step 3: Run the Script

Execute the script with the release parameter:

# Get dates for release 4.21
python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 4.21

# Get dates for release 4.20
python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 4.20

Step 4: Process the Output

The script outputs JSON data with the following structure:

{
  "release": "4.21",
  "found": true,
  "ga": "2026-02-17T00:00:00Z",
  "development_start": "2025-09-02T00:00:00Z",
  "previous_release": "4.20"
}

Field Descriptions:

  • release: The release identifier that was queried
  • found: Boolean indicating if the release exists in Sippy
  • ga: GA (General Availability) date. If null, the release is still in development.
  • development_start: When development started for this release
  • previous_release: The previous release in the sequence (empty string if none)

If Release Not Found:

{
  "release": "99.99",
  "found": false
}

Release Status - Development vs GA'd:

  • In Development: If ga is null, the release is still under active development
    {
      "release": "4.21",
      "found": true,
      "development_start": "2025-09-02T00:00:00Z",
      "previous_release": "4.20"
    }
    
  • GA'd (Released): If ga has a timestamp, the release has reached General Availability
    {
      "release": "4.17",
      "found": true,
      "ga": "2024-10-01T00:00:00Z",
      "development_start": "2024-05-17T00:00:00Z",
      "previous_release": "4.16"
    }
    

Step 5: Use the Information

Based on the release dates:

  1. Determine release status: Check if release is in development or GA'd
    • If ga is null: Release is still in development
    • If ga has a timestamp: Release has reached General Availability
  2. Determine release timeline: Use development_start and ga dates
    • Calculate time in development: ga - development_start
    • For in-development releases: Calculate time since development_start
  3. Find related releases: Use previous_release to navigate the release sequence
  4. Validate release: Check found field before using the release in other operations

Error Handling

The script handles several error scenarios:

  1. Network Errors: If unable to reach Sippy API

    Error: URL Error: [reason]
    
  2. HTTP Errors: If API returns an error status

    Error: HTTP Error 404: Not Found
    
  3. Invalid Release: Script returns exit code 1 with found: false in output

  4. Parsing Errors: If API response is malformed

    Error: Failed to fetch release dates: [details]
    

Output Format

The script outputs JSON to stdout with:

  • Success: Exit code 0, JSON with found: true
  • Release Not Found: Exit code 1, JSON with found: false
  • Error: Exit code 1, error message to stderr

API Details

The script queries the Sippy releases API:

The full API response includes:

  • releases: Array of all available release identifiers
  • ga_dates: Simple mapping of release to GA date
  • dates: Detailed mapping with GA and development_start dates
  • release_attrs: Extended attributes including previous release

Examples

Example 1: Get Current Development Release

python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 4.21

Output:

{
  "release": "4.21",
  "found": true,
  "development_start": "2025-09-02T00:00:00Z",
  "previous_release": "4.20"
}

Example 2: Get GA'd Release

python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 4.17

Output:

{
  "release": "4.17",
  "found": true,
  "ga": "2024-10-01T00:00:00Z",
  "development_start": "2024-05-17T00:00:00Z",
  "previous_release": "4.16"
}

Example 3: Query Non-Existent Release

python3 plugins/teams/skills/get-release-dates/get_release_dates.py \
  --release 99.99

Output:

{
  "release": "99.99",
  "found": false
}

Exit code: 1

Integration with Other Commands

This skill can be used in conjunction with other teams skills:

  1. Before analyzing regressions: Verify the release exists
  2. Timeline context: Understand how long a release has been in development
  3. Release status: Determine if a release is in development or has GA'd
  4. Release navigation: Find previous/next releases in the sequence

Notes

  • The script uses Python's standard library only (no external dependencies)
  • API responses are cached by Sippy, so repeated calls are fast
  • Release identifiers are case-sensitive (use "4.21" not "4.21.0")
  • OKD releases are suffixed with "-okd" (e.g., "4.21-okd")
  • ARO releases have special identifiers (e.g., "aro-production")
  • "Presubmits" is a special release for pull request data

See Also

List Components

This skill provides functionality to list all OCPBUGS component names from the team component mapping, with optional filtering by team.

When to Use This Skill

Use this skill when you need to:

  • Display all OCPBUGS component names
  • Display OCPBUGS components for a specific team
  • Validate OCPBUGS component names before using them in other commands
  • Get a complete list of OCPBUGS-tracked components
  • Count how many OCPBUGS components are in the system or per team
  • Find component names for filing or querying OCPBUGS issues

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. jq Installation

    • Check if installed: which jq
    • Required for JSON parsing
    • Usually pre-installed on most systems
    • macOS: brew install jq
    • Linux: sudo apt-get install jq or sudo yum install jq
  3. Team Component Mapping File

    • The mapping file team_component_map.json should be in the repository
    • Located at: plugins/teams/team_component_map.json
    • This file is committed to the repository - no download needed
    • To regenerate: python3 plugins/teams/generate_team_component_map.py

Implementation Steps

Step 1: Verify Repository

Ensure you are in the repository root directory:

# Verify you are in the repository root
pwd
# Expected output: /path/to/ai-helpers

Step 2: Run the list-components Script

List all OCPBUGS components:

python3 plugins/teams/skills/list-components/list_components.py

List OCPBUGS components for a specific team:

python3 plugins/teams/skills/list-components/list_components.py --team "API Server"

Note: Use the exact team name from the list-teams command output.

Step 3: Process the Output

The script outputs JSON with the following structure:

All components:

{
  "total_components": 87,
  "components": [
    "Auth",
    "apiserver-auth",
    "config-operator",
    "..."
  ]
}

Components filtered by team:

{
  "total_components": 8,
  "components": [
    "apiserver-auth",
    "config-operator",
    "kube-apiserver",
    "kube-controller-manager",
    "kube-storage-version-migrator",
    "openshift-apiserver",
    "openshift-controller-manager / controller-manager",
    "service-ca"
  ],
  "team": "API Server"
}

Field Descriptions:

  • total_components: Total number of OCPBUGS components found
  • components: Alphabetically sorted list of OCPBUGS component names
  • team: (Optional) The team name used for filtering

Error Handling

The script handles several error scenarios:

  1. Mapping file missing:

    Error: Team component mapping file not found at ...
    This file should be in the repository. Please check your installation.
    

    Solution: Verify repository checkout or regenerate with generate_team_component_map.py

  2. Invalid JSON in mapping:

    Error: Failed to parse mapping file. File may be corrupted.
    

    Solution: Regenerate the mapping file

  3. Team not found:

    Error: Team 'Invalid Team' not found in mapping.
    Use list-teams to see available teams.
    

    Solution: Run list-teams to get correct team name, ensure exact match (case-sensitive)

  4. No OCPBUGS components for team:

    Warning: No OCPBUGS components found for team 'Team Name'.
    The team may not have any OCPBUGS components assigned.
    

    Note: This is a warning, not an error. Some teams may not have OCPBUGS components.

Output Format

The script outputs JSON to stdout:

  • Success: Exit code 0, JSON with component list
  • Error: Exit code 1, error message to stderr

Examples

Example 1: List All Components

python3 plugins/teams/skills/list-components/list_components.py

Output:

{
  "total_components": 87,
  "components": [
    "Auth",
    "apiserver-auth",
    "..."
  ]
}

Example 2: List Components for a Specific Team

python3 plugins/teams/skills/list-components/list_components.py --team "API Server"

Output:

{
  "total_components": 8,
  "components": [
    "apiserver-auth",
    "config-operator",
    "kube-apiserver",
    "..."
  ],
  "team": "API Server"
}

Example 3: Count Components

python3 plugins/teams/skills/list-components/list_components.py | jq '.total_components'

Output:

87

Example 4: Search for Specific Component

python3 plugins/teams/skills/list-components/list_components.py | jq '.components[] | select(contains("apiserver"))'

Output:

"apiserver-auth"
"kube-apiserver"
"openshift-apiserver"

Notes

  • Only OCPBUGS components are included in the mapping
  • Team names must match exactly (case-sensitive) - use list-teams to get correct names
  • When filtering by team, only components owned by that team are returned
  • Component names are case-sensitive
  • Components are returned in alphabetical order
  • The script reads from the committed mapping file (no network calls)
  • Very fast execution (< 100ms typically)
  • Mapping file location: plugins/teams/team_component_map.json
  • Component names can be used directly in OCPBUGS JIRA queries and other teams commands
  • Typical count: ~87 total components across 29 teams (may vary as components are added/removed)
  • To refresh mapping: Run python3 plugins/teams/generate_team_component_map.py

Data Source

The team and component mapping data originates from:

If data looks wrong or missing:

  1. Submit a PR to https://gitlab.cee.redhat.com/hybrid-platforms/org to correct the source data
  2. After the PR merges, regenerate the mapping file in this repository:
    python3 plugins/teams/generate_team_component_map.py
    
  3. Commit the updated team_component_map.json file

See Also

  • Related Skill: plugins/teams/skills/list-teams/SKILL.md
  • Related Command: /teams:list-components
  • Mapping File: plugins/teams/team_component_map.json
  • Generator Script: plugins/teams/generate_team_component_map.py

List JIRAs

This skill provides functionality to query JIRA bugs for a specified project and return raw issue data. It uses the JIRA REST API to fetch complete bug information with all fields and metadata, without performing any summarization.

When to Use This Skill

Use this skill when you need to:

  • Fetch raw JIRA issue data for further processing
  • Access complete issue details including all fields
  • Build custom analysis workflows
  • Provide data to other commands (like summarize-jiras)
  • Export JIRA data for offline analysis

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. JIRA Authentication

  3. Network Access

    • The script requires network access to reach your JIRA instance
    • Ensure you can make HTTPS requests to the JIRA URL

Implementation Steps

Step 1: Verify Prerequisites

First, ensure Python 3 is available:

python3 --version

If Python 3 is not installed, guide the user through installation for their platform.

Step 2: Verify Environment Variables

Check that required environment variables are set:

# Verify JIRA credentials are configured
echo "JIRA_URL: ${JIRA_URL}"
echo "JIRA_USERNAME: ${JIRA_USERNAME}"
echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+***set***}"

If any are missing, guide the user to set them:

export JIRA_URL="https://redhat.atlassian.net"
export JIRA_USERNAME="your-email@redhat.com"
export JIRA_API_TOKEN="your-api-token-here"

Step 3: Locate the Script

The script is located at:

plugins/teams/skills/list-jiras/list_jiras.py

Step 4: Run the Script

Execute the script with appropriate arguments:

# Basic usage - all open bugs in a project
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS

# Filter by component
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver"

# Filter by multiple components
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver" "Management Console"

# Include closed bugs
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --include-closed

# Filter by status
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --status New "In Progress"

# Set maximum results limit (default 100)
python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --limit 500

Step 5: Process the Output

The script outputs JSON data with the following structure:

{
  "project": "OCPBUGS",
  "total_count": 1500,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "issues": [
    {
      "key": "OCPBUGS-12345",
      "fields": {
        "summary": "Bug title here",
        "status": {
          "name": "New",
          "id": "1"
        },
        "priority": {
          "name": "Major",
          "id": "3"
        },
        "components": [
          {"name": "kube-apiserver", "id": "12345"}
        ],
        "assignee": {
          "displayName": "John Doe",
          "emailAddress": "jdoe@example.com"
        },
        "created": "2025-11-01T10:30:00.000+0000",
        "updated": "2025-11-05T14:20:00.000+0000",
        "resolutiondate": null,
        "versions": [
          {"name": "4.21"}
        ],
        "fixVersions": [
          {"name": "4.22"}
        ],
        "customfield_10855": "4.22.0"
      }
    },
    ...more issues...
  ],
  "note": "Showing first 100 of 1500 total results. Increase --limit for more data."
}

Field Descriptions:

  • project: The JIRA project queried
  • total_count: Total number of matching issues in JIRA (from search results)
  • fetched_count: Number of issues actually fetched (limited by --limit parameter)
  • query: The JQL query executed (includes filter for recently closed bugs)
  • filters: Applied filters (components, statuses, include_closed, limit)
  • issues: Array of raw JIRA issue objects, each containing:
    • key: Issue key (e.g., "OCPBUGS-12345")
    • fields: Object containing all JIRA fields for the issue:
      • summary: Issue title/summary
      • status: Status object with name and ID
      • priority: Priority object with name and ID
      • components: Array of component objects
      • assignee: Assignee object with user details
      • created: Creation timestamp
      • updated: Last updated timestamp
      • resolutiondate: Resolution timestamp (null if not closed)
      • versions: Affects Version/s array
      • fixVersions: Fix Version/s array
      • customfield_10855: Target Version (custom field)
      • And many other JIRA fields as applicable
  • note: Informational message if results are truncated

Important Notes:

  • By default, the query includes: Open bugs + bugs closed in the last 30 days
  • This allows tracking of recent closure activity alongside current open bugs
  • The script fetches a maximum number of issues (default 1000, configurable with --limit)
  • The total_count represents all matching issues in JIRA
  • The returned data includes ALL fields for each issue, providing complete information
  • For large datasets, increase the --limit parameter to fetch more issues
  • Issues can have multiple components
  • All JIRA field data is preserved in the raw format

Step 6: Present Results

Based on the raw JIRA data:

  1. Inform the user about the total count vs fetched count
  2. Explain that the raw data includes all JIRA fields
  3. Suggest using /teams:summarize-jiras if they need summary statistics
  4. The raw issue data can be passed to other commands for further processing
  5. Highlight any truncation and suggest increasing --limit if needed

Error Handling

Common Errors

  1. Authentication Errors

    • Symptom: HTTP 401 Unauthorized
    • Solution: Verify JIRA_USERNAME and JIRA_API_TOKEN are correct
    • Check: Ensure token has not expired
  2. Network Errors

    • Symptom: URLError or connection timeout
    • Solution: Check network connectivity and JIRA_URL is accessible
    • Retry: The script has a 30-second timeout, consider retrying
  3. Invalid Project

    • Symptom: HTTP 400 or empty results
    • Solution: Verify the project key is correct (e.g., "OCPBUGS", not "ocpbugs")
  4. Missing Environment Variables

    • Symptom: Error message about missing credentials
    • Solution: Set required environment variables (JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN)
  5. Rate Limiting

    • Symptom: HTTP 429 Too Many Requests
    • Solution: Wait before retrying, reduce query frequency

Debugging

Enable verbose output by examining stderr:

python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS 2>&1 | tee debug.log

Script Arguments

Required Arguments

  • --project: JIRA project key to query
    • Format: Project key (e.g., "OCPBUGS", "OCPSTRAT")
    • Must be a valid JIRA project

Optional Arguments

  • --component: Filter by component names

    • Values: Space-separated list of component names
    • Default: None (returns all components)
    • Case-sensitive matching
    • Examples: --component "kube-apiserver" "Management Console"
  • --status: Filter by status values

    • Values: Space-separated list of status names
    • Default: None (returns all statuses except Closed)
    • Examples: --status New "In Progress" Verified
  • --include-closed: Include closed bugs in the results

    • Default: false (only open bugs)
    • When specified, includes bugs in "Closed" status
  • --limit: Maximum number of issues to fetch

    • Default: 100
    • Maximum: 1000 (JIRA API limit per request)
    • Higher values provide more accurate statistics but slower performance

Output Format

The script outputs JSON with metadata and raw issue data:

{
  "project": "OCPBUGS",
  "total_count": 5430,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "issues": [
    {
      "key": "OCPBUGS-12345",
      "fields": {
        "summary": "Example bug",
        "status": {"name": "New"},
        "priority": {"name": "Major"},
        "components": [{"name": "kube-apiserver"}],
        "created": "2025-11-01T10:30:00.000+0000",
        ...
      }
    },
    ...
  ],
  "note": "Showing first 100 of 5430 total results. Increase --limit for more data."
}

Examples

Example 1: List All Open Bugs

python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS

Expected Output: JSON containing raw issue data for all open bugs in OCPBUGS project

Example 2: Filter by Component

python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver"

Expected Output: JSON containing raw issue data for the kube-apiserver component only

Example 3: Include Closed Bugs

python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --include-closed \
  --limit 500

Expected Output: JSON containing raw issue data for both open and closed bugs (up to 500 issues)

Example 4: Filter by Multiple Components

python3 plugins/teams/skills/list-jiras/list_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver" "etcd" "Networking"

Expected Output: JSON containing raw issue data for bugs in specified components

Integration with Commands

This skill is designed to:

  • Provide raw JIRA data to other commands (like summarize-jiras)
  • Be used directly for ad-hoc JIRA queries
  • Serve as a data source for custom analysis workflows
  • Export JIRA data for offline processing

Related Skills

  • summarize-jiras: Calculate summary statistics from JIRA data
  • list-regressions: Fetch regression data for releases
  • analyze-regressions: Grade component health based on regressions
  • get-release-dates: Fetch OpenShift release dates

Notes

  • The script uses Python's urllib and json modules (no external dependencies)
  • Output is always JSON format for easy parsing and further processing
  • Diagnostic messages are written to stderr, data to stdout
  • The script has a 30-second timeout for HTTP requests
  • For large projects, use component filters to reduce query size
  • The returned data includes ALL JIRA fields for complete information
  • Use /teams:summarize-jiras if you need summary statistics instead of raw data

List Regressions

This skill provides functionality to fetch regression data for OpenShift components across different releases. It uses a Python script to query a component health API and retrieve regression information.

When to Use This Skill

Use this skill when you need to:

  • Analyze component health for a specific OpenShift release
  • Track regressions across releases
  • Filter regressions by their open/closed status
  • Generate reports on component stability

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. Network Access

    • The script requires network access to reach the component health API
    • Ensure you can make HTTPS requests
  3. API Endpoint Configuration

    • The script includes a placeholder API endpoint that needs to be updated
    • Update the base_url in list_regressions.py with the actual component health API endpoint

Implementation Steps

Step 1: Verify Prerequisites

First, ensure Python 3 is available:

python3 --version

If Python 3 is not installed, guide the user through installation for their platform.

Step 2: Locate the Script

The script is located at:

plugins/teams/skills/list-regressions/list_regressions.py

Step 3: Run the Script

Execute the script with appropriate arguments:

# Basic usage - all regressions for a view
python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main

# Filter by specific components (case-insensitive, hierarchy-aware:
# "Installer" also matches "Installer / openshift-installer";
# "Networking" matches "Networking / ovn-kubernetes", "Networking / router", ...)
python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.21-main \
  --components Monitoring "kube-apiserver"

# Filter by multiple components
python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.21-main \
  --components Monitoring etcd "kube-apiserver"

# Filter by development window (GA'd release - both start and end)
python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main \
  --start 2024-05-17 \
  --end 2024-10-01

# Filter by development window (in-development release - start only)
python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.22-main \
  --start 2025-09-02

Step 4: Process the Output

The script outputs JSON data with the following structure:

{
  "summary": {
    "total": <number>,
    "triaged": <number>,
    "triage_percentage": <number>,
    "time_to_triage_hrs_avg": <number or null>,
    "time_to_triage_hrs_max": <number or null>,
    "time_to_resolve_hrs_avg": <number or null>,
    "time_to_resolve_hrs_max": <number or null>,
    "open": {
      "total": <number>,
      "triaged": <number>,
      "triage_percentage": <number>,
      "time_to_triage_hrs_avg": <number or null>,
      "time_to_triage_hrs_max": <number or null>,
      "open_hrs_avg": <number or null>,
      "open_hrs_max": <number or null>
    },
    "closed": {
      "total": <number>,
      "triaged": <number>,
      "triage_percentage": <number>,
      "time_to_triage_hrs_avg": <number or null>,
      "time_to_triage_hrs_max": <number or null>,
      "time_to_resolve_hrs_avg": <number or null>,
      "time_to_resolve_hrs_max": <number or null>
    }
  },
  "components": {
    "ComponentName": {
      "summary": {
        "total": <number>,
        "triaged": <number>,
        "triage_percentage": <number>,
        "time_to_triage_hrs_avg": <number or null>,
        "time_to_triage_hrs_max": <number or null>,
        "time_to_resolve_hrs_avg": <number or null>,
        "time_to_resolve_hrs_max": <number or null>,
        "open": {
          "total": <number>,
          "triaged": <number>,
          "triage_percentage": <number>,
          "time_to_triage_hrs_avg": <number or null>,
          "time_to_triage_hrs_max": <number or null>,
          "open_hrs_avg": <number or null>,
          "open_hrs_max": <number or null>
        },
        "closed": {
          "total": <number>,
          "triaged": <number>,
          "triage_percentage": <number>,
          "time_to_triage_hrs_avg": <number or null>,
          "time_to_triage_hrs_max": <number or null>,
          "time_to_resolve_hrs_avg": <number or null>,
          "time_to_resolve_hrs_max": <number or null>
        }
      },
      "open": [...],
      "closed": [...]
    }
  }
}

CRITICAL: The output includes pre-calculated counts and health metrics:

  • summary: Overall statistics across all components
    • summary.total: Total number of regressions
    • summary.triaged: Total number of regressions triaged (open + closed)
    • summary.triage_percentage: Percentage of all regressions that have been triaged (KEY HEALTH METRIC)
    • summary.time_to_triage_hrs_avg: Overall average hours to triage (combining open and closed, KEY HEALTH METRIC)
    • summary.time_to_triage_hrs_max: Overall maximum hours to triage
    • summary.time_to_resolve_hrs_avg: Overall average hours to resolve regressions, measured from regression opened to triage resolved timestamp (KEY HEALTH METRIC)
    • summary.time_to_resolve_hrs_max: Overall maximum hours to resolve regressions
    • summary.open.total: Number of open regressions (where closed is null)
    • summary.open.triaged: Number of open regressions that have been triaged to a JIRA bug
    • summary.open.triage_percentage: Percentage of open regressions triaged
    • summary.open.time_to_triage_hrs_avg: Average hours from opened to first triage (open only)
    • summary.open.time_to_triage_hrs_max: Maximum hours from opened to first triage (open only)
    • summary.open.open_hrs_avg: Average hours that open regressions have been open (from opened to current time)
    • summary.open.open_hrs_max: Maximum hours that open regressions have been open (from opened to current time)
    • summary.closed.total: Number of closed regressions (where closed is not null)
    • summary.closed.triaged: Number of closed regressions that have been triaged to a JIRA bug
    • summary.closed.triage_percentage: Percentage of closed regressions triaged
    • summary.closed.time_to_triage_hrs_avg: Average hours from opened to first triage (closed only)
    • summary.closed.time_to_triage_hrs_max: Maximum hours from opened to first triage (closed only)
    • summary.closed.time_to_resolve_hrs_avg: Average hours from regression opened to triage resolved (JIRA bug completed), null if no valid data
    • summary.closed.time_to_resolve_hrs_max: Maximum hours from regression opened to triage resolved, null if no valid data
  • components: Dictionary mapping component names to objects containing:
    • summary: Per-component statistics (includes same fields as overall summary)
    • open: Array of open regression objects for that component
    • closed: Array of closed regression objects for that component

Time to Triage Calculation:

The time_to_triage_hrs_avg field is calculated as:

  1. For each triaged regression, find the earliest created_at timestamp in the triages array
  2. Calculate the time difference between the regression's opened timestamp and the earliest triage timestamp
  3. Convert the difference to hours and round to the nearest hour
  4. Only include positive time differences (zero or negative values are skipped - these occur when triages are reused across regression instances)
  5. Average all valid time-to-triage values for open regressions separately from closed regressions
  6. Return null if no regressions have valid time-to-triage data in that category

Time to Resolve Calculation:

The time_to_resolve_hrs_avg and time_to_resolve_hrs_max fields (only for triaged closed regressions) are calculated as:

  1. For each closed regression that has been triaged, find the earliest resolved timestamp among the triage objects
  2. The triage resolved timestamp indicates when the linked JIRA bug moved to a completed state
  3. Calculate the time difference between the regression's opened timestamp and the earliest triage resolved timestamp
  4. Convert the difference to hours and round to the nearest hour
  5. Only include positive time differences (skip data inconsistencies)
  6. Calculate average and maximum of all valid time-to-resolve values
  7. Return null if no triaged closed regressions have valid resolved timestamps

Note: This metric uses the triage resolved timestamp rather than the regression closed timestamp because the regression closing (bad data rolling off component readiness) can lag by a week or more after the underlying issue is fixed. The triage resolved timestamp provides a more accurate measure of how quickly a team addressed the issue.

Open Duration Calculation:

The open_hrs_avg and open_hrs_max fields (only for open regressions) are calculated as:

  1. For each open regression, calculate the time difference between opened timestamp and current time
  2. Convert the difference to hours and round to the nearest hour
  3. Only include positive time differences
  4. Calculate average and maximum of all open duration values
  5. Return null if no open regressions have valid time data

ALWAYS use these summary counts rather than attempting to count the regression arrays yourself. This ensures accuracy even when the output is truncated due to size.

The script automatically simplifies and optimizes the response:

Time field simplification (closed and last_failure):

  • Original API format: {"Time": "2025-09-27T12:04:24.966914Z", "Valid": true}
  • Simplified format: "closed": "2025-09-27T12:04:24.966914Z" (if Valid is true)
  • Or: "closed": null (if Valid is false)
  • Same applies to last_failure field

Field removal for response size optimization:

  • links: Removed from each regression (reduces response size significantly)
  • test_id: Removed from each regression (large field, can be reconstructed from test_name if needed)

Date filtering (optional):

  • Use --start and --end parameters to filter regressions to a specific time window
  • --start YYYY-MM-DD: Excludes regressions that were closed before this date
  • --end YYYY-MM-DD: Excludes regressions that were opened after this date
  • Typical use case: Filter to the development window
    • --start: development_start date from get-release-dates skill (always applied)
    • --end: GA date from get-release-dates skill (only for GA'd releases)
  • For GA'd releases: Both start and end filtering applied
  • For in-development releases (null GA date): Only start filtering applied (no end date)
  • Benefits: Focuses analysis on regressions during active development, excluding:
    • Regressions closed before the release development started (not relevant)
    • Regressions opened after GA (post-release, often not monitored/triaged - GA'd releases only)

Parse this JSON output to extract relevant information for analysis.

Step 5: Generate Analysis (Optional)

Based on the regression data:

  1. Use the summary counts from the summary and components.*.summary objects (do NOT count the arrays)
  2. Identify most affected components using components.*.summary.open.total
  3. Compare with previous releases
  4. Analyze trends in open vs closed regressions per component
  5. Create visualizations if needed

Error Handling

Common Errors

  1. Network Errors

    • Symptom: URLError or connection timeout
    • Solution: Check network connectivity and firewall rules
    • Retry: The script has a 30-second timeout, consider retrying
  2. HTTP Errors

    • Symptom: HTTP 404, 500, etc.
    • Solution: Verify the API endpoint URL is correct
    • Check: Ensure the release parameter is valid
  3. Invalid Release

    • Symptom: Empty results or error response
    • Solution: Verify the release format (e.g., "4.17", not "v4.17")
  4. Invalid Boolean Value

    • Symptom: ValueError: Invalid boolean value
    • Solution: Use only "true" or "false" for the --opened flag

Debugging

Enable verbose output by examining stderr:

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17 2>&1 | tee debug.log

Script Arguments

Required Arguments

  • --view: View name to query
    • Format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
    • The release is derived from the view name automatically
    • Multiple views can exist per release (e.g., "4.22-main", "4.22-main-mass-failure")

Optional Arguments

  • --components: Filter by component names

    • Values: Space-separated list of component names
    • Default: None (returns all components)
    • Case-insensitive matching
    • Examples: --components Monitoring etcd "kube-apiserver"
    • Filtering is performed after fetching data from the API
  • --test-name: Filter by exact test name

    • Value: Exact test name string (case-sensitive)
    • Returns only regressions for this specific test across all variants and components
    • Useful for finding all variant-specific regressions for a single test
    • Example: --test-name "[Monitor:kubelet-container-restarts][sig-architecture] platform pods in ns/openshift-machine-config-operator should not exit an excessive amount of times"
  • --test-name-contains: Filter by test name substring

    • Value: Substring to search for within test names (case-insensitive)
    • Returns regressions whose test name contains the given string
    • Useful for finding related tests in the same namespace or sig
    • Example: --test-name-contains "openshift-machine-config-operator"

Output Format

The script outputs JSON with summaries and regressions grouped by component:

{
  "summary": {
    "total": 62,
    "triaged": 59,
    "triage_percentage": 95.2,
    "time_to_triage_hrs_avg": 68,
    "time_to_triage_hrs_max": 240,
    "time_to_resolve_hrs_avg": 168,
    "time_to_resolve_hrs_max": 480,
    "open": {
      "total": 2,
      "triaged": 1,
      "triage_percentage": 50.0,
      "time_to_triage_hrs_avg": 48,
      "time_to_triage_hrs_max": 48,
      "open_hrs_avg": 120,
      "open_hrs_max": 200
    },
    "closed": {
      "total": 60,
      "triaged": 58,
      "triage_percentage": 96.7,
      "time_to_triage_hrs_avg": 72,
      "time_to_triage_hrs_max": 240,
      "time_to_resolve_hrs_avg": 168,
      "time_to_resolve_hrs_max": 480
    }
  },
  "components": {
    "Monitoring": {
      "summary": {
        "total": 15,
        "triaged": 13,
        "triage_percentage": 86.7,
        "time_to_triage_hrs_avg": 68,
        "time_to_triage_hrs_max": 180,
        "time_to_resolve_hrs_avg": 156,
        "time_to_resolve_hrs_max": 360,
        "open": {
          "total": 1,
          "triaged": 0,
          "triage_percentage": 0.0,
          "time_to_triage_hrs_avg": null,
          "time_to_triage_hrs_max": null,
          "open_hrs_avg": 72,
          "open_hrs_max": 72
        },
        "closed": {
          "total": 14,
          "triaged": 13,
          "triage_percentage": 92.9,
          "time_to_triage_hrs_avg": 68,
          "time_to_triage_hrs_max": 180,
          "time_to_resolve_hrs_avg": 156,
          "time_to_resolve_hrs_max": 360
        }
      },
      "open": [
        {
          "id": 12894,
          "component": "Monitoring",
          "closed": null,
          ...
        }
      ],
      "closed": [
        {
          "id": 12893,
          "view": "4.21-main",
          "release": "4.21",
          "base_release": "4.18",
          "component": "Monitoring",
          "capability": "operator-conditions",
          "test_name": "...",
          "variants": [...],
          "opened": "2025-09-26T00:02:51.385944Z",
          "closed": "2025-09-27T12:04:24.966914Z",
          "triages": [],
          "last_failure": "2025-09-25T14:41:17Z",
          "max_failures": 9
        }
      ]
    },
    "etcd": {
      "summary": {
        "total": 20,
        "triaged": 19,
        "triage_percentage": 95.0,
        "time_to_triage_hrs_avg": 84,
        "time_to_triage_hrs_max": 220,
        "time_to_resolve_hrs_avg": 192,
        "time_to_resolve_hrs_max": 500,
        "open": {
          "total": 0,
          "triaged": 0,
          "triage_percentage": 0.0,
          "time_to_triage_hrs_avg": null,
          "time_to_triage_hrs_max": null,
          "open_hrs_avg": null,
          "open_hrs_max": null
        },
        "closed": {
          "total": 20,
          "triaged": 19,
          "triage_percentage": 95.0,
          "time_to_triage_hrs_avg": 84,
          "time_to_triage_hrs_max": 220,
          "time_to_resolve_hrs_avg": 192,
          "time_to_resolve_hrs_max": 500
        }
      },
      "open": [],
      "closed": [...]
    },
    "kube-apiserver": {
      "summary": {
        "total": 27,
        "triaged": 27,
        "triage_percentage": 100.0,
        "time_to_triage_hrs_avg": 58,
        "time_to_triage_hrs_max": 168,
        "time_to_resolve_hrs_avg": 144,
        "time_to_resolve_hrs_max": 400,
        "open": {
          "total": 1,
          "triaged": 1,
          "triage_percentage": 100.0,
          "time_to_triage_hrs_avg": 36,
          "time_to_triage_hrs_max": 36,
          "open_hrs_avg": 96,
          "open_hrs_max": 96
        },
        "closed": {
          "total": 26,
          "triaged": 26,
          "triage_percentage": 100.0,
          "time_to_triage_hrs_avg": 60,
          "time_to_triage_hrs_max": 168,
          "time_to_resolve_hrs_avg": 144,
          "time_to_resolve_hrs_max": 400
        }
      },
      "open": [...],
      "closed": [...]
    }
  }
}

Important - Summary Objects:

  • The summary object contains overall pre-calculated counts for accuracy
  • Each component in the components object has its own summary with per-component counts
  • The components object maps component names (sorted alphabetically) to objects containing:
    • summary: Statistics for this component (total, open, closed)
    • open: Array of open regression objects (where closed is null)
    • closed: Array of closed regression objects (where closed has a timestamp)
  • ALWAYS use the summary and components.*.summary fields for counts (including total, open.total, open.triaged, closed.total, closed.triaged)
  • Do NOT attempt to count the components.*.open or components.*.closed arrays yourself

Note: Time fields are simplified from the API response:

  • closed: If the regression is closed: "closed": "2025-09-27T12:04:24.966914Z" (timestamp string), otherwise null
  • last_failure: If valid: "last_failure": "2025-09-25T14:41:17Z" (timestamp string), otherwise null

Examples

Example 1: List All Regressions

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.17-main

Expected Output: JSON containing all regressions for the 4.17-main view

Example 2: Filter by Component

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.21-main \
  --components Monitoring etcd

Expected Output: JSON containing regressions for only Monitoring and etcd components in the 4.21-main view

Example 3: Filter by Single Component

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.21-main \
  --components "kube-apiserver"

Expected Output: JSON containing regressions for the kube-apiserver component in the 4.21-main view

Example 4: Filter by Exact Test Name

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.22-main \
  --test-name "[Monitor:kubelet-container-restarts][sig-architecture] platform pods in ns/openshift-machine-config-operator should not exit an excessive amount of times"

Expected Output: JSON containing all regressions (across all components and variants) for this exact test in the 4.22-main view. Useful for finding the same test failing in different variant combinations.

Example 5: Filter by Test Name Substring

python3 plugins/teams/skills/list-regressions/list_regressions.py \
  --view 4.22-main \
  --test-name-contains "openshift-machine-config-operator"

Expected Output: JSON containing all regressions whose test name contains the substring (case-insensitive). Useful for finding related tests in the same namespace or sig.

Note: --test-name and --test-name-contains are mutually exclusive with each other and with --components/--team. They search across all components automatically.

Customization

Updating the API Endpoint

The script includes a placeholder API endpoint. Update it in list_regressions.py:

# Current placeholder
base_url = f"https://teams-api.example.com/api/v1/regressions"

# Update to actual endpoint
base_url = f"https://actual-api.example.com/api/v1/regressions"

Adding Custom Filters

To add additional query parameters, modify the fetch_regressions function:

def fetch_regressions(release: str, opened: Optional[bool] = None,
                     component: Optional[str] = None) -> dict:
    params = [f"release={release}"]
    if opened is not None:
        params.append(f"opened={'true' if opened else 'false'}")
    if component is not None:
        params.append(f"component={component}")
    # ... rest of function

Integration with Commands

This skill is designed to be used by the /teams:analyze-regressions command, but can also be invoked directly by other commands or scripts that need regression data.

Related Skills

  • Component health analysis
  • Release comparison
  • Regression tracking
  • Quality metrics reporting

Notes

  • The script uses Python's built-in urllib module (no external dependencies)
  • Output is always JSON format for easy parsing
  • Diagnostic messages are written to stderr, data to stdout
  • The script has a 30-second timeout for HTTP requests

List Teams

This skill provides functionality to list all teams from the team component mapping, including rich metadata about each team (components, description, repos, team size, slack channels).

When to Use This Skill

Use this skill when you need to:

  • Display all available team names
  • Validate team names before using them in other commands
  • Get a complete list of teams with OCPBUGS components
  • Count how many teams are in the system
  • Find team names for team-based analysis

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
  2. Team Component Mapping File

    • The mapping file should be in the repository
    • Located at: plugins/teams/team_component_map.json
    • This file is committed to the repository

Implementation Steps

Step 1: Run the list-teams Script

python3 plugins/teams/skills/list-teams/list_teams.py

Step 2: Process the Output

The script outputs JSON in one of two formats:

New Format (after regeneration with updated script):

{
  "total_teams": 29,
  "teams": {
    "API Server": {
      "components": ["kube-apiserver", "openshift-apiserver", "..."],
      "description": "Team responsible for API server components",
      "team_size": 15,
      "repos": ["openshift/origin", "openshift/kubernetes"],
      "slack_channels": ["forum-apiserver"]
    },
    "Authentication": {
      "components": ["oauth-apiserver", "..."],
      "description": "...",
      "team_size": 10,
      "repos": ["..."],
      "slack_channels": ["..."]
    }
  }
}

Old Format (before regeneration):

{
  "total_teams": 29,
  "teams": [
    "API Server",
    "Authentication",
    "..."
  ]
}

Step 3: Display to User

Important: When displaying results to the user via the /teams:list-teams command:

  • Show only a concise list of team names
  • Do NOT display the full team metadata unless the user specifically asks for it
  • Keep the output brief and scannable

For AI Agent Use:

  • Full team metadata is available for answering follow-up questions
  • Can use components, repos, slack_channels to provide context
  • Can use team_size and description for additional insights

Examples

Example 1: List All Teams

python3 plugins/teams/skills/list-teams/list_teams.py

Example 2: Count Teams

python3 plugins/teams/skills/list-teams/list_teams.py | jq '.total_teams'

Notes

  • Team data is extracted from the committed mapping file
  • Team names are case-sensitive
  • Teams are returned in alphabetical order by team name
  • Very fast execution (< 100ms)
  • Typical count: ~29 teams (teams with OCPBUGS components only)
  • Script automatically detects format (new vs old) and handles both
  • Rich metadata includes:
    • components: List of OCPBUGS components owned by the team
    • description: Team's purpose/responsibility
    • team_size: Number of team members (count only, no personal info)
    • repos: GitHub repositories the team owns
    • slack_channels: Forum-type Slack channels (names only)

Data Source

The team and component mapping data originates from:

If data looks wrong or missing:

  1. Submit a PR to https://gitlab.cee.redhat.com/hybrid-platforms/org to correct the source data
  2. After the PR merges, regenerate the mapping file in this repository:
    python3 plugins/teams/generate_team_component_map.py
    
  3. Commit the updated team_component_map.json file

See Also

  • Related Skill: plugins/teams/skills/list-components/SKILL.md
  • Related Command: /teams:list-teams
  • Mapping File: plugins/teams/team_component_map.json
  • Generator Script: plugins/teams/generate_team_component_map.py

Summarize JIRAs

This skill provides functionality to query JIRA bugs for a specified project and generate summary statistics. It leverages the list-jiras skill to fetch raw JIRA data, then calculates counts by status, priority, and component to provide insights into the bug backlog.

When to Use This Skill

Use this skill when you need to:

  • Get a count of open bugs in a JIRA project
  • Analyze bug distribution by status, priority, or component
  • Generate summary reports for bug backlog
  • Track bug trends and velocity over time (opened vs closed in last 30 days)
  • Compare bug counts across different components or teams
  • Monitor component health or team health based on bug metrics
  • Get team-level bug summaries across all team components

Prerequisites

  1. Python 3 Installation

    • Check if installed: which python3
    • Python 3.6 or later is required
    • Comes pre-installed on most systems
  2. JIRA Authentication

  3. Network Access

    • The script requires network access to reach your JIRA instance
    • Ensure you can make HTTPS requests to the JIRA URL

Implementation Steps

Step 1: Verify Prerequisites

First, ensure Python 3 is available:

python3 --version

If Python 3 is not installed, guide the user through installation for their platform.

Step 2: Verify Environment Variables

Check that required environment variables are set:

# Verify JIRA credentials are configured
echo "JIRA_URL: ${JIRA_URL}"
echo "JIRA_USERNAME: ${JIRA_USERNAME}"
echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+***set***}"

If any are missing, guide the user to set them:

export JIRA_URL="https://redhat.atlassian.net"
export JIRA_USERNAME="your-email@redhat.com"
export JIRA_API_TOKEN="your-api-token-here"

Step 3: Locate the Script

The script is located at:

plugins/teams/skills/summarize-jiras/summarize_jiras.py

Step 4: Run the Script

Execute the script with appropriate arguments:

# Basic usage - summarize all open bugs in a project
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS

# Filter by component
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver"

# Filter by multiple components
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver" "Management Console"

# Filter by team
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --team "API Server"

# Include closed bugs
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --include-closed

# Filter by status
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --status New "In Progress"

# Set maximum results limit (default 100)
python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --limit 500

Step 5: Process the Output

The script outputs JSON data with the following structure:

{
  "project": "OCPBUGS",
  "total_count": 1500,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "summary": {
    "total": 100,
    "opened_last_30_days": 15,
    "closed_last_30_days": 8,
    "by_status": {
      "New": 35,
      "In Progress": 25,
      "Verified": 20,
      "Modified": 15,
      "ON_QA": 5,
      "Closed": 8
    },
    "by_priority": {
      "Normal": 50,
      "Major": 30,
      "Minor": 12,
      "Critical": 5,
      "Undefined": 3
    },
    "by_component": {
      "kube-apiserver": 25,
      "Management Console": 30,
      "Networking": 20,
      "etcd": 15,
      "No Component": 10
    }
  },
  "components": {
    "kube-apiserver": {
      "total": 25,
      "opened_last_30_days": 4,
      "closed_last_30_days": 2,
      "by_status": {
        "New": 10,
        "In Progress": 8,
        "Verified": 5,
        "Modified": 2,
        "Closed": 2
      },
      "by_priority": {
        "Major": 12,
        "Normal": 10,
        "Minor": 2,
        "Critical": 1
      }
    },
    "Management Console": {
      "total": 30,
      "opened_last_30_days": 6,
      "closed_last_30_days": 3,
      "by_status": {
        "New": 12,
        "In Progress": 10,
        "Verified": 6,
        "Modified": 2,
        "Closed": 3
      },
      "by_priority": {
        "Normal": 18,
        "Major": 8,
        "Minor": 3,
        "Critical": 1
      }
    },
    "etcd": {
      "total": 15,
      "opened_last_30_days": 3,
      "closed_last_30_days": 2,
      "by_status": {
        "New": 8,
        "In Progress": 4,
        "Verified": 3,
        "Closed": 2
      },
      "by_priority": {
        "Normal": 10,
        "Major": 4,
        "Critical": 1
      }
    }
  },
  "note": "Showing first 100 of 1500 total results. Increase --limit for more accurate statistics."
}

Field Descriptions:

  • project: The JIRA project queried
  • total_count: Total number of matching issues (from JIRA search results)
  • fetched_count: Number of issues actually fetched (limited by --limit parameter)
  • query: The JQL query executed (includes filter for recently closed bugs)
  • filters: Applied filters (components, statuses, include_closed, limit)
  • summary: Overall statistics across all fetched issues
    • total: Count of fetched issues (same as fetched_count)
    • opened_last_30_days: Number of issues created in the last 30 days
    • closed_last_30_days: Number of issues closed/resolved in the last 30 days
    • by_status: Count of issues per status (includes recently closed issues)
    • by_priority: Count of issues per priority
    • by_component: Count of issues per component (note: issues can have multiple components)
  • components: Per-component breakdown with individual summaries
    • Each component key maps to:
      • total: Number of issues assigned to this component
      • opened_last_30_days: Number of issues created in the last 30 days for this component
      • closed_last_30_days: Number of issues closed in the last 30 days for this component
      • by_status: Status distribution for this component
      • by_priority: Priority distribution for this component
  • note: Informational message if results are truncated

Important Notes:

  • By default, the query includes: Open bugs + bugs closed in the last 30 days
  • This allows tracking of recent closure activity alongside current open bugs
  • The script fetches a maximum number of issues (default 100, configurable with --limit)
  • The total_count represents all matching issues in JIRA
  • Summary statistics are based on the fetched issues only
  • For accurate statistics across large datasets, increase the --limit parameter
  • Issues can have multiple components, so component totals may sum to more than the overall total
  • opened_last_30_days and closed_last_30_days help track recent bug flow and velocity

Step 6: Present Results

Based on the summary data:

  1. Present total bug counts
  2. Highlight distribution by status (e.g., how many in "New" vs "In Progress")
  3. Identify priority breakdown (Critical, Major, Normal, etc.)
  4. Show component distribution
  5. Display per-component breakdowns with status and priority counts
  6. Calculate actionable metrics (e.g., New + Assigned = bugs needing triage/work)
  7. Highlight recent activity (opened/closed in last 30 days) per component

Error Handling

Common Errors

  1. Authentication Errors

    • Symptom: HTTP 401 Unauthorized
    • Solution: Verify JIRA_URL, JIRA_USERNAME, and JIRA_API_TOKEN are correct
    • Check: Ensure token has not expired
  2. Network Errors

    • Symptom: URLError or connection timeout
    • Solution: Check network connectivity and JIRA_URL is accessible
    • Retry: The script has a 30-second timeout, consider retrying
  3. Invalid Project

    • Symptom: HTTP 400 or empty results
    • Solution: Verify the project key is correct (e.g., "OCPBUGS", not "ocpbugs")
  4. Missing Environment Variables

    • Symptom: Error message about missing credentials
    • Solution: Set required environment variables (JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN)
  5. Rate Limiting

    • Symptom: HTTP 429 Too Many Requests
    • Solution: Wait before retrying, reduce query frequency

Debugging

Enable verbose output by examining stderr:

python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS 2>&1 | tee debug.log

Script Arguments

Required Arguments

  • --project: JIRA project key to query
    • Format: Project key (e.g., "OCPBUGS", "OCPSTRAT")
    • Must be a valid JIRA project

Optional Arguments

  • --component: Filter by component names

    • Values: Space-separated list of component names
    • Default: None (returns all components)
    • Case-sensitive matching
    • Examples: --component "kube-apiserver" "Management Console"
  • --status: Filter by status values

    • Values: Space-separated list of status names
    • Default: None (returns all statuses except Closed)
    • Examples: --status New "In Progress" Verified
  • --include-closed: Include closed bugs in the results

    • Default: false (only open bugs)
    • When specified, includes bugs in "Closed" status
  • --limit: Maximum number of issues to fetch

    • Default: 100
    • Maximum: 1000 (JIRA API limit per request)
    • Higher values provide more accurate statistics but slower performance

Output Format

The script outputs JSON with summary statistics and per-component breakdowns:

{
  "project": "OCPBUGS",
  "total_count": 5430,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "summary": {
    "total": 100,
    "opened_last_30_days": 15,
    "closed_last_30_days": 8,
    "by_status": {
      "New": 1250,
      "In Progress": 800,
      "Verified": 650
    },
    "by_priority": {
      "Critical": 50,
      "Major": 450,
      "Normal": 2100
    },
    "by_component": {
      "kube-apiserver": 146,
      "Management Console": 392
    }
  },
  "components": {
    "kube-apiserver": {
      "total": 146,
      "opened_last_30_days": 20,
      "closed_last_30_days": 12,
      "by_status": {...},
      "by_priority": {...}
    }
  },
  "note": "Showing first 100 of 5430 total results. Increase --limit for more accurate statistics."
}

Examples

Example 1: Summarize All Open Bugs

python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS

Expected Output: JSON containing summary statistics of all open bugs in OCPBUGS project

Example 2: Filter by Component

python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver"

Expected Output: JSON containing summary for the kube-apiserver component only

Example 3: Include Closed Bugs

python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --include-closed \
  --limit 500

Expected Output: JSON containing summary of both open and closed bugs (up to 500 issues)

Example 4: Filter by Multiple Components

python3 plugins/teams/skills/summarize-jiras/summarize_jiras.py \
  --project OCPBUGS \
  --component "kube-apiserver" "etcd" "Networking"

Expected Output: JSON containing summary for specified components

Integration with Commands

This skill is designed to:

  • Provide summary statistics for JIRA bug analysis
  • Be used by component health analysis workflows
  • Generate reports for bug triage and planning
  • Track component health metrics over time
  • Leverage the list-jiras skill for raw data fetching

Related Skills

  • list-jiras: Fetch raw JIRA issue data
  • list-regressions: Fetch regression data for releases
  • analyze-regressions: Grade component health based on regressions
  • get-release-dates: Fetch OpenShift release dates

Notes

  • The script uses Python's standard library only (no external dependencies)
  • Output is always JSON format for easy parsing
  • Diagnostic messages are written to stderr, data to stdout
  • The script internally calls list_jiras.py to fetch raw data
  • The script has a 30-second timeout for HTTP requests (inherited from list_jiras.py)
  • For large projects, use component filters to reduce query size
  • Summary statistics are based on fetched issues (controlled by --limit), not total matching issues
  • For raw JIRA data without summarization, use /teams:list-jiras instead

Commands 10

Name

teams:coderabbit-adoption-report

Synopsis

/teams:coderabbit-adoption-report
/teams:coderabbit-adoption-report --start-date 2026-02-01 --end-date 2026-02-28

Description

The teams:coderabbit-adoption-report command measures CodeRabbit Pro adoption across a curated list of ~160 OCP payload repositories by calculating what percentage of merged PRs received a Pro-tier CodeRabbit review (identified by "Plan: Pro" in the comment body).

The list of repos to scan is defined in plugins/teams/skills/coderabbit-adoption/allowed-repos.txt.

It uses a Python script that calls the GitHub search API via gh CLI. The script does one org-wide query for PRs with Pro reviews, then batched queries (20 repos per batch) for all merged PRs. Per-repo breakdowns are calculated in Python. Takes about a minute to complete with progress shown.

How CodeRabbit Pro Reviews Work

CodeRabbit was enabled across most OCP payload repos on 2026-03-09. Since many of these repos are open source, CodeRabbit may leave comments on any PR — but only Pro reviews (indicated by Plan: Pro in the CodeRabbit comment) provide the full-quality analysis we want.

CodeRabbit does not review bot PRs. PRs authored by bot accounts (e.g., dependabot[bot], github-actions[bot], openshift-monitoring-bot[bot]) are intentionally skipped by CodeRabbit. Bot PRs appearing in the "missed" list are expected and should not be counted against adoption.

The script uses "Plan: Pro" as a search term combined with commenter:coderabbitai[bot] to directly identify Pro-reviewed PRs, then compares against all merged PRs to find the gap.

The script filters to PRs created on or after the enablement date (2026-03-09) to avoid counting old long-lived PRs that merged after enablement but were never seen by CodeRabbit.

Arguments

  • --start-date YYYY-MM-DD (optional): Start of the date range for merged PRs. Defaults to 7 days ago.
  • --end-date YYYY-MM-DD (optional): End of the date range for merged PRs. Defaults to today.

Implementation

Prerequisites

  • GitHub CLI (gh): Must be installed and authenticated with access to the openshift org.
  • Python 3: Python 3.6 or later is required.

Steps

  1. Verify prerequisites:

    gh auth status
    python3 --version
    
  2. Run the Python script with arguments passed through from the command.

    # Default (last 7 days)
    python3 plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py
    
    # With date range
    python3 plugins/teams/skills/coderabbit-adoption/coderabbit_adoption.py \
      --start-date 2026-02-01 --end-date 2026-02-28
    

    The script handles all GitHub API orchestration:

    • Query 1 (paginated, ~5 API calls): Org-wide search for PRs with commenter:coderabbitai[bot] "Plan: Pro", filtered to allowed repos.
    • Query 2 (~8 batched API calls): All merged PRs across allowed repos in batches of 20, with 3-second sleeps and retry logic for rate limits.

    All queries include a created:>=2026-03-09 filter to exclude PRs opened before CodeRabbit was enabled.

  3. Parse the JSON output and format the report. The script outputs all data needed: summary stats, missed PRs with URLs, and per-user breakdowns.

    Detect partial data: Check if truncated is true. When true, GitHub search pagination hit its limits (1000 items max). Insert a warning notice in the report.

    ## CodeRabbit Adoption Report
    
    **Date Range**: <start_date> to <end_date>
    **PRs created on or after**: <cr_enablement_date>
    
    ### Summary
    - Repos scanned: <total_allowed_repos>
    - Repos with activity: <repos_with_activity>
    - Total merged PRs: <total_merged_prs>
    - PRs with Pro review: <prs_with_pro_review>
    - Adoption rate: <adoption_pct>%
    
    ### PRs Without Pro Review (<missed_prs_count>)
    | Repository | PR | Author | Bot? |
    |---|---|---|---|
    | openshift/console | [#16138](https://github.com/openshift/console/pull/16138) | rhamilto | No |
    | openshift/ironic-image | [#816](https://github.com/openshift/ironic-image/pull/816) | github-actions[bot] | Yes |
    
    ### Users Without Pro Reviews (<count>)
    Users who authored merged PRs but whose PRs did not receive a Pro CodeRabbit review.
    Bot accounts are excluded.
    | User | Repos |
    |---|---|
    | @username | openshift/repo-a, openshift/repo-b |
    
    ### Repos with No Activity
    <repos_without_activity_count> repos had no merged PRs in this date range.
    
  4. Offer to copy report to clipboard: After presenting the report, ask the user if they'd like the full markdown report copied to their clipboard. If they accept, use pbcopy (macOS) or xclip/xsel (Linux) to copy the complete report.

  5. AI Analysis: After presenting the data, provide brief observations:

    • Highlight any non-bot missed PRs as the key action items
    • Bot PRs are intentionally not reviewed by CodeRabbit (by design, not a timing issue) and are expected in the missed list
    • Non-bot missed PRs are worth investigating (possible config gaps or other issues)
    • Any notable patterns in the missed PRs

Return Value

  • Markdown report: Summary statistics, missed PRs table, and user breakdown
  • Adoption percentage: Overall Pro review adoption rate
  • Analysis: Brief observations on missed PRs

Examples

  1. Default (last 7 days):

    /teams:coderabbit-adoption-report
    
  2. Specific month:

    /teams:coderabbit-adoption-report --start-date 2026-02-01 --end-date 2026-02-28
    

Notes

  • Scoped to payload repos: Only repos listed in plugins/teams/skills/coderabbit-adoption/allowed-repos.txt are included. Edit that file to change scope. The list can be regenerated from a release payload with:
    oc adm release info --commits 4.12.0 -o json | \
      jq '.references.spec.tags[].annotations["io.openshift.build.source-location"]' -r | \
      uniq | sort -u > plugins/teams/skills/coderabbit-adoption/allowed-repos.txt
    
  • Created-date filter: The script automatically filters to PRs created on or after 2026-03-09 (when CodeRabbit was enabled on most repos). This is hardcoded in the script as CR_ENABLEMENT_DATE and prevents old long-lived PRs from skewing adoption numbers.
  • API usage: ~15 API calls total with 3-second sleeps and retry logic for rate limits. One org-wide paginated query for Pro reviews, plus 8 batched queries for all merged PRs (20 repos per batch).
  • The Python script uses gh api -X GET for all GitHub API calls (the -X GET flag is required for the search endpoint).
  • Uses "Plan: Pro" as a search term combined with commenter:coderabbitai[bot] to directly identify Pro-reviewed PRs via GitHub's full-text search.
  • The adoption percentage is calculated across all repos with merged PRs in the date range.

See Also

Name

teams:coderabbit-inheritance-scanner

Synopsis

/teams:coderabbit-inheritance-scanner
/teams:coderabbit-inheritance-scanner --dry-run

Description

The teams:coderabbit-inheritance-scanner command scans all repositories in the openshift GitHub organization that contain a .coderabbit.yaml or .coderabbit.yml file and verifies each one has inheritance: true set. This ensures repos with custom CodeRabbit configurations still inherit the org-wide review rules defined in openshift/coderabbit.

The openshift/coderabbit repo itself is excluded from results since it is the source of the global rules.

After scanning, the command offers to open PRs on non-compliant repos to add inheritance: true. PRs are always opened from a personal fork to avoid needing direct push access to upstream repos.

Arguments

  • --dry-run: Perform all scanning and checks (including searching for existing PRs) but do not actually create forks, push branches, or open PRs. Displays exactly what would be done for each non-compliant repo.

Implementation

Prerequisites

  • GitHub CLI (gh): Must be installed and authenticated with access to the openshift org.
    gh auth status
    
    The token must have the workflow scope to sync forks that contain GitHub Actions workflow files. If missing, warn the user and skip those repos rather than failing.

Steps

  1. Search for .coderabbit.yaml files across the openshift org using the teams:coderabbit-inheritance-scanner-search skill. Use GitHub code search via gh api to find repos efficiently.

  2. For each repo, fetch the raw file and check for inheritance: true. Use the teams:coderabbit-inheritance-scanner-check skill to classify each repo as compliant, non-compliant (missing key), non-compliant (explicitly false), or error.

  3. For each non-compliant repo, check for an existing open PR whose title contains "CodeRabbit inheritance" (case-insensitive substring match, since teams sometimes modify the PR title to satisfy merge requirements). Use the teams:coderabbit-inheritance-scanner-existing-pr skill. Record the PR URL and how long it has been open.

  4. Format and present the results as a markdown report:

    ## CodeRabbit Inheritance Scanner Report
    
    ### Summary
    - Total repos with .coderabbit.yaml: <count>
    - Compliant (inheritance: true): <count>
    - Non-compliant: <count>
    - Existing fix PRs open: <count>
    
    ### Repos with `inheritance: false` (explicitly disabled)
    | Repository | File Link | Existing PR |
    |---|---|---|
    | openshift/<repo> | [.coderabbit.yaml](link) | [#123](link) (open 5 days) |
    
    ### Repos missing `inheritance` key
    | Repository | File Link | Existing PR |
    |---|---|---|
    | openshift/<repo> | [.coderabbit.yaml](link) | None |
    
    ### Compliant repos (inheritance: true)
    <collapsed list>
    
    ### Errors (could not fetch file)
    <list if any>
    
  5. Offer to open fix PRs for non-compliant repos that do not already have an open PR. Present the list and ask for confirmation (unless --dry-run).

    • If --dry-run: Display what would be done for each repo (fork, sync, branch, commit, PR) and stop.
    • If not --dry-run: Ask the user "Open PRs for these N repos? (y/n)" and proceed only on confirmation.
  6. Open fix PRs using the teams:coderabbit-inheritance-scanner-open-pr skill for each repo that needs a PR. This skill handles forking, syncing, branching, committing, pushing, and creating the PR. Collect all created PR URLs.

  7. Present final results with links to all created PRs.

Skills Used

This command delegates to the following skills:

  • teams:coderabbit-inheritance-scanner-search - Search for repos with .coderabbit.yaml files
  • teams:coderabbit-inheritance-scanner-check - Check a repo's .coderabbit.yaml for inheritance: true
  • teams:coderabbit-inheritance-scanner-existing-pr - Search for an existing fix PR on a repo
  • teams:coderabbit-inheritance-scanner-open-pr - Fork, sync, and open a fix PR on a repo

Examples

  1. Scan only (report + offer to fix):

    /teams:coderabbit-inheritance-scanner
    
  2. Dry run (report + show what would be done, no PRs opened):

    /teams:coderabbit-inheritance-scanner --dry-run
    

Notes

  • Uses GitHub code search API to efficiently find repos with .coderabbit.yaml files without iterating all ~800 repos.
  • Searches for both .coderabbit.yaml and .coderabbit.yml extensions.
  • The openshift/coderabbit repository is excluded since it defines the global rules.
  • PRs are always opened from the authenticated user's fork, never by pushing directly to upstream repos.
  • Before opening a PR, the fork's default branch is synced with upstream to ensure the PR is based on the latest code.
  • If gh repo sync fails due to missing workflow scope, the repo is skipped with a warning.
  • Private repos may be skipped depending on gh authentication scope; this is acceptable.
  • GitHub code search API may have a short indexing delay, so very recently added files might not appear.
  • Rate limiting pauses are included between API calls to avoid hitting GitHub rate limits.

See Also

Name

teams:coderabbit-rules-from-pr-reviews

Synopsis

/teams:coderabbit-rules-from-pr-reviews openshift/origin
/teams:coderabbit-rules-from-pr-reviews https://github.com/openshift/origin
/teams:coderabbit-rules-from-pr-reviews openshift/origin --count 50

Description

The teams:coderabbit-rules-from-pr-reviews command analyzes human review comments on recent merged PRs in a GitHub repository to identify recurring review feedback patterns that could be codified as CodeRabbit review rules in the repo's .coderabbit.yaml file.

The command fetches the most recent N merged PRs (default: 30), collects all human review comments (excluding comments from coderabbitai[bot] and other bots), and uses AI analysis to identify patterns that appear across multiple PRs. Only patterns that are likely to recur in future PRs are proposed as rules -- obscure, one-off, or minor issues are ignored.

After analysis, the command offers to open a PR against the repo that adds or updates the .coderabbit.yaml with the proposed rules. It also checks for a CONTRIBUTING.md and adds a reference to the CodeRabbit review rules if one is missing. The command is designed to be re-run periodically -- it compares proposed rules against existing rules and only adds net-new ones.

Arguments

  • <repo> (required): The GitHub repository to analyze. Accepts either:
    • Full URL: https://github.com/openshift/origin
    • Short form: openshift/origin
  • --count N (optional): Number of recent merged PRs to analyze. Default: 30. Higher values give better pattern detection but take longer.

Implementation

Prerequisites

  • GitHub CLI (gh): Must be installed and authenticated with access to the target repo.

  • Python 3: Python 3.6 or later.

    gh auth status
    python3 --version
    

Steps

  1. Parse the repo argument: Extract owner/repo from the argument. If a full GitHub URL is provided, strip the https://github.com/ prefix. Validate the format is owner/repo.

  2. Fetch and filter PR review comments: Run the Python script from the teams:coderabbit-rules-from-pr-reviews skill to collect human review comments:

    python3 plugins/teams/skills/coderabbit-rules-from-pr-reviews/fetch_pr_comments.py <owner/repo> --count <N>
    

    The script handles all GitHub API calls, bot filtering, noise removal, and rate limiting. It outputs JSON to stdout with all filtered human review comments. See the skill documentation for output format details.

    Save the JSON output for analysis in the next step.

  3. Analyze comments for patterns: Parse the JSON output from the script. Analyze the collected human review comments to identify:

    • Recurring patterns: Issues or feedback that appears in 3+ different PRs, or from 2+ different reviewers on similar topics
    • Categories to look for:
      • Code style and formatting issues (naming conventions, import ordering, etc.)
      • Error handling patterns (missing error checks, swallowed errors, etc.)
      • Testing gaps (missing tests for edge cases, missing negative tests, etc.)
      • API/interface misuse (deprecated APIs, incorrect usage patterns, etc.)
      • Documentation gaps (missing godoc, unclear comments, etc.)
      • Security concerns (hardcoded values, missing input validation, etc.)
      • Performance issues (unnecessary allocations, missing context propagation, etc.)
      • Go-specific patterns (if applicable): nil checks, goroutine leaks, defer misuse, etc.
      • Kubernetes/OpenShift patterns (if applicable): label conventions, finalizer handling, status update patterns, etc.

    What to ignore:

    • One-off issues specific to a single PR's logic
    • Minor nitpicks that wouldn't meaningfully improve code quality
    • Subjective style preferences from a single reviewer
    • Comments that are questions or discussions rather than actionable feedback
    • Merge conflict or rebase-related comments
  4. Check existing CodeRabbit config: Fetch the repo's current .coderabbit.yaml (or .coderabbit.yml) if it exists:

    gh api repos/<owner/repo>/contents/.coderabbit.yaml --jq '.content' 2>/dev/null | base64 -d
    

    If a config exists, parse all existing path_instructions rules and compare them against the proposed rules. De-duplicate: drop any proposed rule whose intent is already covered by an existing rule (same path pattern with overlapping instruction content). Only present net-new rules in the report. This ensures the command can be re-run periodically without creating redundant rules.

  5. Format the output as a report: Present findings as a structured report:

    ## CodeRabbit Rules from PR Reviews: <owner/repo>
    
    **PRs analyzed**: <count>
    **Review comments collected**: <total_human_comments>
    **Reviewers represented**: <unique_reviewer_count>
    
    ### Proposed New Rules
    
    For each identified pattern (only rules not already in existing config):
    
    #### Rule <N>: <Short descriptive title>
    
    **Pattern**: <Description of what reviewers are catching>
    **Evidence**: Found in <X> PRs by <Y> different reviewers
    **Example PRs**: #123, #456, #789
    **Example comments**:
    > <quoted reviewer comment from PR #123>
    > <quoted reviewer comment from PR #456>
    
    **Proposed `.coderabbit.yaml` rule**:
    ```yaml
    reviews:
      path_instructions:
        - path: "<glob pattern>"
          instructions: |
            <instruction text>
    

    Already Covered by Existing Rules

    <List any patterns found in reviews that are already addressed by existing .coderabbit.yaml rules, with brief explanation of which existing rule covers it>

    Summary

    • Total patterns identified:
    • Already covered by existing rules:
    • Net-new rules proposed:

    Existing Config

    <Show current .coderabbit.yaml contents if present, or state that none exists>

  6. Offer to open a PR: After presenting the report, ask the user:

    Would you like me to open a PR to add these rules to the repo's .coderabbit.yaml?

    If the user declines, stop here. If the user accepts, proceed with steps 7-12.

  7. Fork and clone the repo: Use a temporary working directory. Fork the repo (idempotent) and clone it:

    REPO="<owner/repo>"
    REPO_NAME="${REPO##*/}"
    GH_USER=$(gh api user --jq '.login')
    WORKDIR="/tmp/cr-rules-workdir/${REPO_NAME}"
    BRANCH_NAME="coderabbit-rules-from-reviews"
    UPSTREAM_DEFAULT=$(gh repo view "${REPO}" --json defaultBranchRef --jq '.defaultBranchRef.name')
    
    # Fork (idempotent)
    gh repo fork "${REPO}" --clone=false 2>&1 || true
    sleep 2
    
    # The fork's default branch may differ from upstream (e.g., fork uses "master"
    # while upstream uses "main"). Detect the fork's actual default branch.
    FORK_DEFAULT=$(gh repo view "${GH_USER}/${REPO_NAME}" --json defaultBranchRef --jq '.defaultBranchRef.name')
    
    # Sync fork's default branch with upstream's default branch
    gh repo sync "${GH_USER}/${REPO_NAME}" --source "${REPO}" --branch "${FORK_DEFAULT}" 2>&1
    
    # Delete stale branch from previous runs
    gh api -X DELETE "repos/${GH_USER}/${REPO_NAME}/git/refs/heads/${BRANCH_NAME}" 2>/dev/null || true
    sleep 1
    
    # Clone using the fork's default branch, then create a working branch
    rm -rf "${WORKDIR}"
    gh repo clone "${GH_USER}/${REPO_NAME}" "${WORKDIR}" -- -b "${FORK_DEFAULT}" --depth 1
    cd "${WORKDIR}"
    git checkout -b "${BRANCH_NAME}"
    

    Important: Use UPSTREAM_DEFAULT (not FORK_DEFAULT) as the PR base branch in step 11, since the PR targets the upstream repo.

  8. Create or update .coderabbit.yaml: In the cloned repo:

    • If no .coderabbit.yaml exists: Create a new file with inheritance: true at the top (so org-wide rules are preserved) followed by the proposed path_instructions rules:

      inheritance: true
      reviews:
        path_instructions:
          - path: "<glob>"
            instructions: |
              <instruction>
      
    • If .coderabbit.yaml already exists: Parse the existing file and merge in the new rules. Append new path_instructions entries after existing ones. Do not modify or remove any existing content. Preserve inheritance: true if present; add it if missing. Preserve all existing YAML structure, comments, and formatting as much as possible.

  9. Check and update CONTRIBUTING.md: Look for CONTRIBUTING.md or CONTRIBUTING (case-insensitive) in the repo root:

    ls -1 "${WORKDIR}" | grep -i '^contributing'
    
    • If a contributing file exists: Check if it already references .coderabbit.yaml or CodeRabbit review rules (case-insensitive search). If not, append a section:

      
      ## Automated Code Review
      
      This repository uses [CodeRabbit](https://coderabbit.ai) for automated code review.
      Review rules are defined in [`.coderabbit.yaml`](.coderabbit.yaml) and encode
      common patterns identified from past PR reviews. Please review these rules when
      contributing to understand the standards enforced during automated review.
      
    • If no contributing file exists: Do nothing -- do not create a CONTRIBUTING.md from scratch, as the repo may intentionally not have one.

  10. Commit the changes: Create a single commit with all changes:

    git add .coderabbit.yaml
    # Only add CONTRIBUTING.md if it was modified
    git diff --name-only | grep -i contributing && git add CONTRIBUTING.md CONTRIBUTING contributing.md 2>/dev/null || true
    
    git commit -m "$(cat <<'COMMITEOF'
    Add CodeRabbit review rules derived from PR review patterns
    
    Analyzed recent merged PRs to identify recurring review feedback patterns
    and codified them as CodeRabbit path_instructions rules. These rules help
    catch common issues automatically during code review.
    
    Generated by teams:coderabbit-rules-from-pr-reviews
    COMMITEOF
    )"
    
  11. Push and open PR:

    git push origin "${BRANCH_NAME}"
    
    gh pr create \
      --repo "${REPO}" \
      --head "${GH_USER}:${BRANCH_NAME}" \
      --base "${UPSTREAM_DEFAULT}" \
      --title "Add CodeRabbit review rules from PR review patterns" \
      --body "$(cat <<'BODYEOF'
    ## Summary
    
    This PR adds CodeRabbit review rules to `.coderabbit.yaml` based on patterns
    identified from analyzing recent merged PR review comments. These rules encode
    recurring feedback from human reviewers so that CodeRabbit can catch the same
    issues automatically in future PRs.
    
    ### Rules added
    
    <list each rule title and a one-line description>
    
    ### How these were identified
    
    Analyzed the most recent <N> merged PRs and collected human review comments
    (excluding bots, approvals, and prow commands). Patterns appearing in 3+ PRs
    or from 2+ different reviewers were proposed as rules.
    
    ### Re-running
    
    This command can be re-run periodically to identify new patterns:
    

    /teams:coderabbit-rules-from-pr-reviews <owner/repo>

    It compares against existing rules and only proposes net-new additions.
    
    Generated by `teams:coderabbit-rules-from-pr-reviews`
    BODYEOF
    )"
    

    Important: Customize the PR body before creating it. Replace the <list each rule title...> placeholder with the actual rules being added, and replace <N> with the actual PR count analyzed.

  12. Report the result: Display the PR URL to the user. Clean up by noting the temp directory path but do not delete it (in case the user wants to inspect it).

Skills Used

This command delegates to the following skill:

  • teams:coderabbit-rules-from-pr-reviews - Fetch and filter human review comments from recent merged PRs

Return Value

  • Markdown report: Identified patterns, evidence, and proposed CodeRabbit rules
  • YAML snippets: Ready-to-use .coderabbit.yaml rule definitions
  • PR URL: Link to the opened PR (if user accepted)

Examples

  1. Analyze default number of PRs:

    /teams:coderabbit-rules-from-pr-reviews openshift/origin
    
  2. Analyze more PRs for better pattern detection:

    /teams:coderabbit-rules-from-pr-reviews openshift/origin --count 50
    
  3. Using full URL:

    /teams:coderabbit-rules-from-pr-reviews https://github.com/openshift/cluster-kube-apiserver-operator
    

Notes

  • Idempotent / re-runnable: The command compares proposed rules against the repo's existing .coderabbit.yaml and only proposes net-new rules. This makes it safe to re-run periodically to keep rules up to date as new review patterns emerge.
  • Fork-based PRs: PRs are always opened from the authenticated user's fork, never by pushing directly to the upstream repo. The fork is created automatically if it doesn't exist.
  • Stale branch cleanup: If the branch coderabbit-rules-from-reviews already exists on the fork (from a previous run), it is deleted before pushing to ensure a clean state.
  • CONTRIBUTING.md: If the repo has a CONTRIBUTING.md, the command adds a reference to .coderabbit.yaml so contributors know about the automated review rules. It does not create a CONTRIBUTING.md if one doesn't exist.
  • Bot filtering: The Python script excludes comments from coderabbitai[bot] and other known bots automatically.
  • Rate limiting: The script adds 0.5s sleeps between API calls with retry logic for rate limit errors. Analyzing 30 PRs typically takes 1-2 minutes.
  • Comment quality: Short comments (<20 chars), pure approvals, and Prow commands are filtered out by the script.
  • Pattern threshold: Only patterns appearing in 3+ PRs or from 2+ different reviewers are proposed as rules. This ensures rules target genuinely recurring issues, not one-off problems.
  • CodeRabbit rule format: Proposed rules use the path_instructions format which associates review instructions with file path glob patterns. See CodeRabbit docs for the full rule specification.
  • Inheritance preserved: When creating or updating .coderabbit.yaml, the command ensures inheritance: true is set so org-wide rules from openshift/coderabbit continue to apply.
  • The command works with any GitHub repository accessible to the authenticated gh user, not just OpenShift repos.

See Also

Name

teams:health-check-jiras

Synopsis

/teams:health-check-jiras --project <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
/teams:health-check-jiras --project <project> --team <team-name> [--status status1 status2 ...] [--include-closed] [--limit N]

Description

The teams:health-check-jiras command queries JIRA bugs for a specified project and generates summary statistics. It leverages the list-jiras command to fetch raw JIRA data and then calculates counts by status, priority, and component to help understand the bug backlog at a glance.

By default, the command includes:

  • All currently open bugs
  • Bugs closed in the last 30 days (to track recent closure activity)

This command is useful for:

  • Getting a quick count of open bugs in a JIRA project
  • Analyzing bug distribution by status, priority, or component
  • Tracking recent bug flow (opened vs closed in last 30 days)
  • Generating summary reports for bug backlog
  • Monitoring bug velocity and closure rates by component or team
  • Comparing bug counts across different components
  • Getting team-level bug summaries across all team components

Implementation

  1. Verify Prerequisites: Check that Python 3 is installed

    • Run: python3 --version
    • Verify version 3.6 or later is available
  2. Verify Environment Variables: Ensure JIRA authentication is configured

    • Check that the following environment variables are set:

      • JIRA_URL: Base URL for JIRA instance (e.g., "https://redhat.atlassian.net")
      • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
      • JIRA_API_TOKEN: Your JIRA API token
    • Verify with:

      echo "JIRA_URL: ${JIRA_URL}"
      echo "JIRA_USERNAME: ${JIRA_USERNAME}"
      echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+***set***}"
      
    • If missing, guide the user to set them:

      export JIRA_URL="https://redhat.atlassian.net"
      export JIRA_USERNAME="your-email@redhat.com"
      export JIRA_API_TOKEN="your-api-token-here"
      
  3. Parse Arguments: Extract project key and optional filters from arguments

    • Project key: Required --project flag (e.g., "OCPBUGS", "OCPSTRAT")
    • Optional filters:
      • --component: Space-separated list of component search strings (fuzzy match)
      • --team: Team name (looks up all components for that team)
      • --status: Space-separated list of status values
      • --include-closed: Flag to include closed bugs
      • --limit: Maximum number of issues to fetch per component (default: 1000, max: 1000)
    • Note: --component and --team are mutually exclusive
  4. Resolve Component Names: Use fuzzy matching or team lookup to find actual component names

    • If --team was provided:
      • The script will handle team component lookup internally via get_team_components()
      • If team not found, display available teams and exit
    • Else if --component was provided:
      • Extract release from context or ask user for release version
      • Run list_components.py to get all available components:
        python3 plugins/teams/skills/list-components/list_components.py
        
      • For each search string in --component:
        • Find all components containing that string (case-insensitive)
        • Combine all matches into a single list
        • Remove duplicates
        • If no matches found for a search string, warn the user and show available components
  5. Execute Python Script: Run the summarize_jiras.py script

    • Script location: plugins/teams/skills/summarize-jiras/summarize_jiras.py
    • The script internally calls list_jiras.py to fetch raw data and handles all components in one invocation
    • If --team was provided:
      • Execute: python3 summarize_jiras.py --project <project> --team "<team>" [other args]
      • Script automatically looks up all team components and queries them
      • Returns team-level summary and per-component breakdowns
    • Else if --component was provided:
      • Execute: python3 summarize_jiras.py --project <project> --component <components> [other args]
      • Script handles all components in one invocation
      • Returns overall summary and per-component breakdowns
    • Else:
      • Execute: python3 summarize_jiras.py --project <project> [other args]
      • Queries all bugs in the project
    • Capture JSON output from stdout
  6. Parse Output: Process the aggregated JSON response

    • Extract summary statistics:
      • total_count: Total matching issues in JIRA
      • fetched_count: Number of issues actually fetched
      • summary.by_status: Count of issues per status
      • summary.by_priority: Count of issues per priority
      • summary.by_component: Count of issues per component
    • Extract per-component breakdowns:
      • Each component has its own counts by status and priority
      • Includes opened/closed in last 30 days per component
  7. Present Results: Display summary in a clear format

    • Show which components were matched (if fuzzy search was used)
    • Show total bug count across all components
    • Display status breakdown (e.g., New, In Progress, Verified, etc.)
    • Display priority breakdown (Critical, Major, Normal, Minor, etc.)
    • Display component distribution
    • Show per-component breakdowns with status and priority counts
    • Highlight any truncation (if fetched_count < total_count for any component)
    • Suggest increasing --limit if results are truncated
  8. Error Handling: Handle common error scenarios

    • Network connectivity issues
    • Invalid JIRA credentials
    • Invalid project key
    • HTTP errors (401, 404, 500, etc.)
    • Rate limiting (429)

Return Value

The command outputs a JIRA Bug Summary with the following information:

Project Overview

  • Project: JIRA project key
  • Total Count: Total number of matching bugs (open + recently closed)
  • Query: JQL query that was executed (includes 30-day closed bug filter)
  • Fetched Count: Number of bugs actually fetched (may be less than total if limited)

Summary Statistics

Overall Metrics:

  • Total bugs fetched
  • Bugs opened in last 30 days
  • Bugs closed in last 30 days

By Status: Count of bugs in each status (includes recently closed)

StatusCount
NewX
In ProgressX
VerifiedX
ClosedX
......

By Priority: Count of bugs by priority level

PriorityCount
CriticalX
MajorX
NormalX
MinorX
UndefinedX

By Component: Count of bugs per component

ComponentCount
kube-apiserverX
Management ConsoleX
NetworkingX
......

Per-Component Breakdown

For each component:

  • Total: Number of bugs assigned to this component
  • Opened (30d): Bugs created in the last 30 days
  • Closed (30d): Bugs closed in the last 30 days
  • By Status: Status distribution for this component
  • By Priority: Priority distribution for this component

Additional Information

  • Filters Applied: Lists any component, status, or other filters used
  • Note: If results are truncated, suggests increasing the limit
  • Query Scope: By default includes open bugs and bugs closed in the last 30 days

Examples

  1. Summarize all open bugs for a project:

    /teams:health-check-jiras --project OCPBUGS
    

    Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and displays summary statistics.

  2. Filter by specific component:

    /teams:health-check-jiras --project OCPBUGS --component "kube-apiserver"
    

    Shows bug counts for only the kube-apiserver component.

  3. Filter by multiple components:

    /teams:health-check-jiras --project OCPBUGS --component "kube-apiserver" "etcd" "Networking"
    

    Shows bug counts for kube-apiserver, etcd, and Networking components.

  4. Include closed bugs:

    /teams:health-check-jiras --project OCPBUGS --include-closed --limit 500
    

    Includes both open and closed bugs, fetching up to 500 issues.

  5. Filter by status:

    /teams:health-check-jiras --project OCPBUGS --status New "In Progress" Verified
    

    Shows only bugs in New, In Progress, or Verified status.

  6. Filter by team:

    /teams:health-check-jiras --project OCPBUGS --team "API Server"
    

    Automatically looks up all components for the "API Server" team and shows bug counts:

    • Queries all team components in one invocation
    • Returns overall team summary
    • Includes per-component breakdowns
  7. Combine multiple filters:

    /teams:health-check-jiras --project OCPBUGS --component "Management Console" --status New Assigned --limit 200
    

    Shows bugs for Management Console component that are in New or Assigned status.

Arguments

  • --project <project> (required): JIRA project key

    • Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
    • Must be a valid JIRA project you have access to
  • Additional optional flags:

    • --component <search1> [search2 ...]: Filter by component names using fuzzy search

      • Space-separated list of component search strings
      • Case-insensitive substring matching
      • Each search string matches all components containing that substring
      • Handles all components in one invocation
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
      • Mutually exclusive with --team
    • --team <team-name>: Filter by team name

      • Looks up all components for the team from team_component_map.json
      • Handles all team components in one invocation
      • Returns overall team summary and per-component breakdowns
      • Use /teams:list-teams to see available team names
      • Team names are case-sensitive
      • Mutually exclusive with --component
    • --status <status1> [status2 ...]: Filter by status values

      • Space-separated list of status names
      • Examples: New, "In Progress", Verified, Modified, ON_QA
    • --include-closed: Include closed bugs in results

      • By default, only open bugs are returned
      • When specified, closed bugs are included
    • --limit <N>: Maximum number of issues to fetch per component

      • Default: 1000
      • Range: 1-1000
      • When using component filters, this limit applies to each component separately
      • Higher values provide more accurate statistics but slower performance

Prerequisites

  1. Python 3: Required to run the data fetching and summarization scripts

    • Check: which python3
    • Version: 3.6 or later
  2. JIRA Authentication: Environment variables must be configured

    • JIRA_URL: Your JIRA instance URL
    • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
    • JIRA_API_TOKEN: Your JIRA API token

    How to get a JIRA API token:

  3. Network Access: Must be able to reach your JIRA instance

    • Ensure HTTPS requests can be made to JIRA_URL
    • Check firewall and VPN settings if needed

Notes

  • The script uses Python's standard library only (no external dependencies)
  • Output is JSON format for easy parsing
  • Diagnostic messages are written to stderr, data to stdout
  • The script has a 30-second timeout for HTTP requests
  • For large projects, use component filters to reduce query size
  • Summary statistics are based on fetched issues (controlled by --limit), not total matching issues
  • If results show truncation, increase the --limit parameter for more accurate statistics
  • This command internally uses /teams:list-jiras to fetch raw data

See Also

  • Skill Documentation: plugins/teams/skills/summarize-jiras/SKILL.md
  • Script: plugins/teams/skills/summarize-jiras/summarize_jiras.py
  • Related Command: /teams:list-jiras (for raw JIRA data)
  • Related Command: /teams:health-check (for combined health analysis)

Name

teams:health-check-regressions

Synopsis

/teams:health-check-regressions <view> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
/teams:health-check-regressions <view> --team <team-name> [--start YYYY-MM-DD] [--end YYYY-MM-DD]

Description

The teams:health-check-regressions command queries regression data for a specified view (e.g., "4.22-main") and generates summary statistics. A view represents a specific regression tracking context within a release — multiple views can exist per release (e.g., "4.22-main", "4.22-main-mass-failure"). The release is derived from the view name automatically. It leverages the list-regressions command to fetch raw regression data filtered to the specified view and then presents counts, percentages, and timing metrics to help understand regression trends at a glance.

By default, the command analyzes:

  • All regressions within the release development window
  • Both open and closed regressions
  • Triage coverage and timing metrics
  • Per-component breakdowns

This command is useful for:

  • Getting a quick count of regressions in a release
  • Analyzing regression distribution by component or team
  • Tracking triage coverage and response times
  • Generating summary reports for regression management
  • Monitoring regression resolution speed by component or team
  • Comparing regression metrics across different components
  • Understanding open vs closed regression breakdown
  • Getting team-level regression summaries across all team components

Implementation

  1. Verify Prerequisites: Check that Python 3 is installed

    • Run: python3 --version
    • Verify version 3.6 or later is available
  2. Parse Arguments: Extract view name and optional filters from arguments

    • View format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
    • The release is derived from the view name (e.g., "4.22" from "4.22-main")
    • Optional filters:
      • --components: Space-separated list of component search strings (fuzzy match)
      • --team: Team name (looks up all components for that team)
      • --start: Start date for filtering (YYYY-MM-DD)
      • --end: End date for filtering (YYYY-MM-DD)
    • Note: --components and --team are mutually exclusive
  3. Resolve Component Names: Use fuzzy matching to find actual component names, or look up by team

    • If --team was provided:
      • Look up all components for that team from team_component_map.json
      • The script will handle this internally via get_team_components()
      • If team not found, display available teams and exit
    • If --components was provided:
      • Run list_components.py to get all available components:
        python3 plugins/teams/skills/list-components/list_components.py
        
      • For each search string, find all components containing that string (case-insensitive)
      • Combine all matches into a single list
      • Remove duplicates
      • If no matches found for a search string, warn the user and show available components
    • If neither --team nor --components was provided:
      • Use all available components from the list
  4. Fetch Release Dates: Run the get_release_dates.py script to get development window dates

    • Script location: plugins/teams/skills/get-release-dates/get_release_dates.py
    • Derive the release from the view name (e.g., "4.22" from "4.22-main")
    • Pass derived release as --release argument
    • Extract development_start and ga dates from JSON output
    • Convert timestamps to simple date format (YYYY-MM-DD)
    • Use these dates if --start and --end are not explicitly provided
  5. Execute Python Script: Run the list_regressions.py script with appropriate arguments

    • Script location: plugins/teams/skills/list-regressions/list_regressions.py
    • Pass view as --view argument (the script derives the release internally)
    • Pass resolved component names as --components argument
    • Pass development_start date as --start argument (if available)
      • Always applied (for both GA'd and in-development releases)
      • Excludes regressions closed before development started
    • Pass ga date as --end argument (only if GA date is not null)
      • Only applied for GA'd releases
      • Excludes regressions opened after GA
      • For in-development releases (null GA date), no end date filtering is applied
    • Always pass --short flag to exclude regression arrays (only summaries)
  6. Parse Output: Process the JSON output from the script

    • Script writes JSON to stdout with summary structure:
      • summary: Overall statistics (total, triaged, percentages, timing)
      • components: Per-component summary statistics
    • ALWAYS use the summary fields for counts and metrics
    • Regression arrays are not included (due to --short flag)
  7. Present Results: Display summary in a clear, readable format

    • Show which components were matched (if fuzzy search was used)
    • Show overall summary statistics
    • For --team mode: Focus presentation on the overall team summary, though per-component data is included in JSON
    • For --components mode: Display per-component breakdowns
    • Highlight key metrics:
      • Triage coverage percentages
      • Average time to triage
      • Average time to resolve (based on triage resolved timestamp)
      • Open vs closed counts
    • Present data in tables or structured format
    • Note any date filtering applied
  8. Error Handling: Handle common error scenarios

    • Network connectivity issues
    • Invalid view format
    • API errors (404, 500, etc.)
    • Empty results
    • No matches for component filter
    • Release dates not found

Return Value

The command outputs a Regression Summary Report with the following information:

Overall Summary

  • View: View name (e.g., "4.22-main")
  • Development Window: Start and end dates (or "In Development" if no GA date)
  • Total Regressions: summary.total
  • Filtered Infrastructure Regressions: summary.filtered_suspected_infra_regressions
  • Triaged: summary.triaged regressions (summary.triage_percentage%)
  • Open: summary.open.total regressions (summary.open.triage_percentage% triaged)
  • Closed: summary.closed.total regressions (summary.closed.triage_percentage% triaged)

Timing Metrics

Overall Metrics:

  • Average Time to Triage: summary.time_to_triage_hrs_avg hours
  • Maximum Time to Triage: summary.time_to_triage_hrs_max hours
  • Average Time to Resolve: summary.time_to_resolve_hrs_avg hours (based on triage resolved timestamp)
  • Maximum Time to Resolve: summary.time_to_resolve_hrs_max hours (based on triage resolved timestamp)

Open Regression Metrics:

  • Average Open Duration: summary.open.open_hrs_avg hours
  • Maximum Open Duration: summary.open.open_hrs_max hours
  • Average Time to Triage (open): summary.open.time_to_triage_hrs_avg hours
  • Maximum Time to Triage (open): summary.open.time_to_triage_hrs_max hours

Closed Regression Metrics:

  • Average Time to Resolve: summary.closed.time_to_resolve_hrs_avg hours (based on triage resolved timestamp)
  • Maximum Time to Resolve: summary.closed.time_to_resolve_hrs_max hours (based on triage resolved timestamp)
  • Average Time to Triage (closed): summary.closed.time_to_triage_hrs_avg hours
  • Maximum Time to Triage (closed): summary.closed.time_to_triage_hrs_max hours

Per-Component Summary

For each component (from components.*.summary):

ComponentTotalOpenClosedTriagedTriage %Avg Time to TriageAvg Time to Resolve
Monitoring151141386.7%68 hrs156 hrs
etcd200201995.0%84 hrs192 hrs
kube-apiserver2712627100.0%58 hrs144 hrs

Additional Information

  • Filters Applied: Lists any component or date filters used
  • Data Scope: Notes which regressions are included based on view and date filtering
    • Regressions are filtered to the specified view (open/closed status comes from the view)
    • For GA'd releases: Regressions within development window (start to GA)
    • For in-development releases: Regressions from development start onwards

Examples

  1. Summarize all regressions for a view:

    /teams:health-check-regressions 4.17-main
    

    Fetches and summarizes all regressions for the 4.17-main view, automatically applying development window date filtering.

  2. Filter by specific component (exact match):

    /teams:health-check-regressions 4.21-main --components Monitoring
    

    Shows summary statistics for only the Monitoring component in the 4.21-main view.

  3. Filter by fuzzy search:

    /teams:health-check-regressions 4.21-main --components network
    

    Finds all components containing "network" (case-insensitive) and shows summary statistics for all matches (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.).

  4. Filter by multiple search strings:

    /teams:health-check-regressions 4.21-main --components etcd kube-
    

    Finds all components containing "etcd" OR "kube-" and shows combined summary statistics.

  5. Specify custom date range:

    /teams:health-check-regressions 4.17-main --start 2024-05-17 --end 2024-10-29
    

    Summarizes regressions within a specific date range:

    • Excludes regressions closed before 2024-05-17
    • Excludes regressions opened after 2024-10-29
  6. In-development release:

    /teams:health-check-regressions 4.22-main
    

    Summarizes regressions for an in-development release view:

    • Automatically fetches development_start date
    • No end date filtering (release not yet GA'd)
    • Shows current state of regression management
  7. Filter by team:

    /teams:health-check-regressions 4.21-main --team "API Server"
    

    Summarizes regressions for all components owned by the "API Server" team:

    • Automatically looks up all team components from team_component_map.json
    • Provides overall team-level summary (not per-component breakdown)
  8. Team summary with custom date range:

    /teams:health-check-regressions 4.17-main --team "Networking" --start 2024-05-17 --end 2024-10-29
    

    Summarizes regressions for the Networking team within a specific date range

Arguments

  • $1 (required): View name

    • Format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
    • The release is derived from the view name (e.g., "4.22" from "4.22-main")
    • Multiple views can exist per release (e.g., "4.22-main", "4.22-main-mass-failure")
  • $2+ (optional): Filter flags

    • --components <search1> [search2 ...]: Filter by component names using fuzzy search

      • Space-separated list of component search strings
      • Case-insensitive substring matching
      • Each search string matches all components containing that substring
      • If no components provided, all components are analyzed
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
      • Mutually exclusive with --team
    • --team <team-name>: Filter by team name

      • Looks up all components for the team from team_component_map.json
      • Returns overall team summary as well as per-component breakdowns in JSON
      • Command presentation should focus on overall team summary
      • Use /teams:list-teams to see available team names
      • Team names are case-sensitive
      • Mutually exclusive with --components
    • --start <YYYY-MM-DD>: Filter by start date

      • Excludes regressions closed before this date
      • Defaults to development_start from release metadata if not provided
    • --end <YYYY-MM-DD>: Filter by end date

      • Excludes regressions opened after this date
      • Defaults to GA date from release metadata if not provided and release is GA'd
      • Omitted for in-development releases

Prerequisites

  1. Python 3: Required to run the data fetching script

    • Check: which python3
    • Version: 3.6 or later
  2. Network Access: Must be able to reach the component health API

    • Ensure HTTPS requests can be made
    • Check firewall and VPN settings if needed
  3. API Configuration: The API endpoint must be configured in the script

    • Location: plugins/teams/skills/list-regressions/list_regressions.py
    • The script should have the correct API base URL

Notes

  • The script uses Python's standard library only (no external dependencies)
  • Output presents summary statistics in a readable format
  • Diagnostic messages are written to stderr
  • The script has a 30-second timeout for HTTP requests
  • Summary statistics are based on all matching regressions (not limited by pagination)
  • The --short flag is always used internally to optimize performance
  • Infrastructure regressions are automatically filtered from counts
  • Date filtering focuses analysis on the development window for accuracy
  • This command internally uses /teams:list-regressions to fetch data
  • For raw regression data, use /teams:list-regressions instead
  • For health grading and analysis, use /teams:health-check instead

See Also

  • Skill Documentation: plugins/teams/skills/list-regressions/SKILL.md
  • Script: plugins/teams/skills/list-regressions/list_regressions.py
  • Related Command: /teams:list-regressions (for raw regression data)
  • Related Command: /teams:health-check (for health grading and analysis)
  • Related Skill: get-release-dates (for fetching development window dates)

Name

teams:health-check

Synopsis

/teams:health-check <release> [--components comp1 comp2 ...] [--project JIRAPROJECT]
/teams:health-check <release> --team <team-name> [--project JIRAPROJECT]

Description

The teams:health-check command provides comprehensive component health analysis for a specified OpenShift release by combining regression management metrics with JIRA bug backlog data.

CRITICAL: This command REQUIRES and AUTOMATICALLY fetches BOTH data sources:

  1. Regression data (via health-check-regressions)
  2. JIRA bug data (via health-check-jiras)

The analysis is INCOMPLETE without both data sources. Both are fetched automatically without user prompting.

The command evaluates component health based on:

  1. Regression Management (ALWAYS fetched automatically): How well components are managing test regressions

    • Triage coverage (% of regressions triaged to JIRA bugs)
    • Triage timeliness (average time from detection to triage)
    • Resolution speed (average time from detection to closure)
  2. Bug Backlog Health (ALWAYS fetched automatically): Current state of open bugs for components

    • Open bug counts by component
    • Bug age distribution
    • Bug priority breakdown
    • Recent bug flow (opened vs closed in last 30 days)

This command is useful for:

  • Sprint planning based on data-driven insights
  • Grading overall component health using multiple quality metrics
  • Identifying components that need help with regression or bug management
  • Tracking quality trends across releases

Grading is subjective and not meant to be a critique of team performance. This is intended to help identify where help is needed and track progress as we improve our quality practices.

Implementation

CRITICAL WORKFLOW: The analyze command MUST execute steps 3 and 4 (fetch regression data AND fetch JIRA data) automatically without waiting for user prompting. Both data sources are required for a complete analysis.

  1. Parse Arguments: Extract release version and required filters from arguments

    • Release format: "X.Y" (e.g., "4.17", "4.21")
    • Required filter (must provide one):
      • --components: Space-separated list of component search strings (fuzzy match)
      • --team: Team name (looks up all components for that team)
    • Optional filters:
      • --project: JIRA project key (default: "OCPBUGS")
    • Note: --components and --team are mutually exclusive
    • Note: One of --components or --team is REQUIRED (analyzing all components is too much data)
  2. Resolve Component Names: Use fuzzy matching to find actual component names, or look up by team

    • Validate required parameter: If neither --team nor --components is provided:
      • Error: "Either --team or --components is required. Analyzing all components is too much data."
      • Show usage examples
      • Exit with error
    • If --team was provided:
      • Look up all components for that team from team_component_map.json
      • Use /teams:list-components --team "<team>" to get the component list
      • If team not found, display available teams (via /teams:list-teams) and exit
    • Else if --components was provided:
      • Run list_components.py to get all available components:
        python3 plugins/teams/skills/list-components/list_components.py
        
      • For each search string, find all components containing that string (case-insensitive)
      • Combine all matches into a single list
      • Remove duplicates
      • If no matches found for a search string, warn the user and show available components
  3. Fetch Regression Summary: REQUIRED - Always call the health-check-regressions command

    IMPORTANT: This step is REQUIRED for the analyze command. Regression data must ALWAYS be fetched automatically without user prompting. The analyze command combines both regression and bug metrics - it is incomplete without both data sources.

    • Fetch regression data automatically for every analysis.
    • If --team was provided:
      • Execute: /teams:health-check-regressions <release> --team "<team>"
    • Else (if --components was provided):
      • Execute: /teams:health-check-regressions <release> --components <resolved-components>
    • Extract regression metrics:
      • Total regressions, triage percentages, timing metrics
      • Per-component breakdowns
      • Open vs closed regression counts
    • Note development window dates for context
    • If regression API is unreachable, inform the user and note this in the report but continue with bug-only analysis
  4. Fetch JIRA Bug Summary: REQUIRED - Always call the health-check-jiras command

    IMPORTANT: This step is REQUIRED for the analyze command. JIRA bug data must ALWAYS be fetched automatically without user prompting. The analyze command combines both regression and bug metrics - it is incomplete without both data sources.

    • ALWAYS execute this step - do not skip or wait for user to request it
    • For each resolved component name:
      • Execute: /teams:health-check-jiras --project <project> --component "<component>" --limit 1000
      • Note: Must iterate over components because JIRA queries can be too large otherwise
    • Aggregate bug metrics across all components:
      • Total open bugs by component
      • Bug age distribution
      • Opened vs closed in last 30 days
      • Priority breakdowns
    • If JIRA authentication is not configured, inform the user and provide setup instructions
    • If JIRA queries fail, note this in the report but continue with regression-only analysis
  5. Calculate Combined Health Grades: REQUIRED - Analyze BOTH regression and bug data

    IMPORTANT: This step requires data from BOTH step 3 (regressions) AND step 4 (JIRA bugs). Do not perform analysis with only one data source unless the other failed to fetch.

    For each component, grade based on:

    a. Regression Health (from step 3: health-check-regressions):

    • Triage Coverage: % of regressions triaged
      • 90-100%: Excellent ✅
      • 70-89%: Good ⚠️
      • 50-69%: Needs Improvement ⚠️
      • <50%: Poor ❌
    • Triage Timeliness: Average hours to triage
      • <24 hours: Excellent ✅
      • 24-72 hours: Good ⚠️
      • 72-168 hours (1 week): Needs Improvement ⚠️
      • 168 hours: Poor ❌

    • Resolution Speed: Average hours to resolve
      • <168 hours (1 week): Excellent ✅
      • 168-336 hours (1-2 weeks): Good ⚠️
      • 336-720 hours (2-4 weeks): Needs Improvement ⚠️
      • 720 hours (4+ weeks): Poor ❌

    b. Bug Backlog Health (from step 4: health-check-jiras):

    • Open Bug Count: Total open bugs
      • Component-relative thresholds (compare across components)
    • Bug Age: Average/maximum age of open bugs
      • <30 days average: Excellent ✅
      • 30-90 days: Good ⚠️
      • 90-180 days: Needs Improvement ⚠️
      • 180 days: Poor ❌

    • Bug Flow: Opened vs closed in last 30 days
      • More closed than opened: Positive trend ✅
      • Equal: Stable ⚠️
      • More opened than closed: Growing backlog ❌

    c. Combined Health Score: Weighted average of regression and bug health

    • Weight regression health more heavily (e.g., 60%) as it's more actionable
    • Bug backlog provides context (40%)
  6. Display Overall Health Report: Present comprehensive analysis combining BOTH data sources

    IMPORTANT: The report MUST include BOTH regression metrics AND JIRA bug metrics. Do not present regression-only analysis unless JIRA data fetch failed.

    • Show which components were matched (if fuzzy search was used)
    • Inform user that both regression and bug data were analyzed

    Section 1: Overall Release Health

    • Release version and development window
    • Overall regression metrics (from health-check-regressions):
      • Total regressions, triage %, timing metrics
    • Overall bug metrics (from health-check-jiras):
      • Total open bugs, opened/closed last 30 days, priority breakdown
    • High-level combined health grade

    Section 2: Per-Component Health Scorecard

    • Ranked table of components from best to worst combined health
    • Key metrics per component (BOTH regression AND bug data):
      • Regression triage coverage
      • Average triage time
      • Average resolution time
      • Open bug count (from JIRA)
      • Bug age metrics (from JIRA)
      • Bug flow (opened vs closed, from JIRA)
      • Combined health grade
    • Visual indicators (✅ ⚠️ ❌) for quick assessment

    Section 3: Components Needing Attention

    • Prioritized list of components with specific issues from BOTH sources
    • Actionable recommendations for each component:
      • "X open untriaged regressions need triage" (only OPEN, not closed)
        • IMPORTANT: Phrase regression triage as a "few hours task", NOT a "sprint"
        • Triaging regressions typically takes a few hours, not an entire 3-week sprint
        • Example: "Triage 5 open regressions (typically a few hours)" ✅
        • Example: "Immediate triage sprint needed" ❌
      • "High bug backlog: X open bugs (Y older than 90 days)" (from JIRA)
      • "Growing bug backlog: +X net bugs in last 30 days" (from JIRA)
      • "Slow regression triage: X hours average"
    • Context for each issue
  7. Offer HTML Report Generation (AFTER displaying the text report):

    • Ask the user if they would like an interactive HTML report
    • If yes, generate an HTML report combining both data sources
    • Use template from: plugins/teams/skills/analyze-regressions/report_template.html
    • Enhance template to include bug backlog metrics
    • Add clickable JIRA links throughout the report:
      • In the component table, make all bug counts clickable with JIRA queries
      • In the "Components Needing Attention" section, link bug counts to JIRA
      • In the "Key Insights" section, link aging bug counts to JIRA
      • In the "Recommendations" section, link action items to JIRA
      • All links should:
        • Use URL-encoded JQL queries (e.g., component%20%3D%20%22oauth-apiserver%22)
        • Open in new tabs (target="_blank")
        • Include helpful tooltips (title attribute)
        • Sort oldest bugs first for aging bug queries (ORDER BY created ASC)
        • Use CSS class .jira-link for consistent styling
      • JIRA link patterns:
        • All bugs: project = OCPBUGS AND component = "X" AND (status != Closed OR resolved >= -30d)
        • Open bugs: project = OCPBUGS AND component = "X" AND status != Closed
        • Bugs 30-90d: project = OCPBUGS AND component = "X" AND status != Closed AND created >= -90d AND created <= -30d
        • Bugs >180d: project = OCPBUGS AND component = "X" AND status != Closed AND created <= -180d ORDER BY created ASC
        • Multi-component: Use component IN ("X", "Y", "Z") for team-wide queries
    • Save report to: .work/teams-health-{release}/health-report.html
    • Open the report in the user's default browser
    • Display the file path to the user
  8. Error Handling: Handle common error scenarios

    • Network connectivity issues
    • Invalid release format
    • Missing regression or JIRA data
    • API errors
    • No matches for component filter
    • JIRA authentication issues

Return Value

The command outputs a Comprehensive Component Health Report:

Overall Health Grade

From combined regression and bug data:

  • Release: OpenShift version and development window
  • Regression Metrics:
    • Total regressions: X (Y% triaged)
    • Average triage time: X hours
    • Average resolution time: X hours
    • Open vs closed breakdown
  • Bug Backlog Metrics:
    • Total open bugs: X across all components
    • Bugs opened/closed in last 30 days
    • Priority distribution
  • Overall Health: Combined grade (Excellent/Good/Needs Improvement/Poor)

Per-Component Health Scorecard

Ranked table combining both metrics:

ComponentRegression TriageTriage TimeResolution TimeOpen BugsBug AgeHealth Grade
kube-apiserver100.0%58 hrs144 hrs1545d avg✅ Excellent
etcd95.0%84 hrs192 hrs830d avg✅ Good
Monitoring86.7%68 hrs156 hrs23120d avg⚠️ Needs Improvement

Components Needing Attention

Prioritized list with actionable items:

1. Monitoring (Needs Improvement):
   - 1 open untriaged regression (needs triage)
   - High bug backlog: 23 open bugs (8 older than 90 days)
   - Growing backlog: +5 net bugs in last 30 days
   - Recommendation: Focus on triaging open regression and addressing oldest bugs

2. Example-Component (Poor):
   - 5 open untriaged regressions (urgent triage needed)
   - Slow triage response: 120 hours average
   - Very high bug backlog: 45 open bugs (15 older than 180 days)
   - Recommendation: Triage 5 open regressions (typically a few hours); consider bug backlog cleanup initiative

IMPORTANT: When listing untriaged regressions:

  • Only list OPEN untriaged regressions - these are actionable
  • Do NOT recommend triaging closed regressions - tooling doesn't support retroactive triage
  • Calculate actionable count as: open.total - open.triaged

Additional Sections

If HTML report is generated:

  • Detailed regression metrics by component
  • Detailed bug breakdowns by status and priority
  • Clickable JIRA links throughout the report:
    • Component table with clickable bug counts
    • "Components Needing Attention" section with linked bug counts
    • "Key Insights" section with linked aging bug counts
    • "Recommendations" section with linked action items
    • All links open JIRA queries in new tabs with proper filtering
  • Interactive filtering (search components, filter by health grade)
  • Links to Sippy dashboards for regression analysis
  • Trends compared to previous releases (if available)

Examples

  1. Analyze team health (recommended):

    /teams:health-check 4.21 --team "API Server"
    

    Automatically fetches BOTH data sources for all components owned by the "API Server" team:

    • Looks up all team components from team_component_map.json
    • Fetches regression metrics for all team components
    • Fetches JIRA bug metrics for all team components
    • Provides comprehensive team-level health analysis
    • Shows per-component breakdowns within the team
    • Identifies which team components need attention
  2. Analyze specific components (exact match):

    /teams:health-check 4.21 --components Monitoring Etcd
    

    Automatically fetches BOTH regression and bug data for Monitoring and Etcd:

    • Compares combined health between the two components
    • Shows regression metrics AND bug backlog for each
    • Identifies which component needs more attention
    • Provides targeted recommendations based on both data sources
  3. Analyze by fuzzy search:

    /teams:health-check 4.21 --components network
    

    Automatically fetches BOTH data sources for all components containing "network":

    • Finds all networking components (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.)
    • Compares combined health across all networking components
    • Shows regression metrics AND bug backlog for each
    • Identifies networking-related quality issues from both sources
    • Provides targeted recommendations
  4. Team analysis with custom JIRA project:

    /teams:health-check 4.21 --team "Networking" --project OCPBUGS
    

    Analyzes health for the Networking team using bugs from OCPBUGS project

Arguments

  • $1 (required): Release version

    • Format: "X.Y" (e.g., "4.17", "4.21")
    • Must be a valid OpenShift release number
  • $2+ (required): Filter flags - must provide either --components or --team

    • --components <search1> [search2 ...]: Filter by component names using fuzzy search

      • Space-separated list of component search strings
      • Case-insensitive substring matching
      • Each search string matches all components containing that substring
      • Applied to both regression and bug queries
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
      • Mutually exclusive with --team
      • Required if --team is not provided
    • --team <team-name>: Filter by team name

      • Looks up all components for the team from team_component_map.json
      • Applied to both regression and bug queries
      • Team-level health analysis with per-component breakdowns
      • Use /teams:list-teams to see available team names
      • Team names are case-sensitive
      • Mutually exclusive with --components
      • Required if --components is not provided
    • --project <PROJECT>: JIRA project key (optional)

      • Default: "OCPBUGS"
      • Use alternative project if component bugs are tracked elsewhere
      • Examples: "OCPSTRAT", "OCPQE"

Prerequisites

  1. Python 3: Required to run the underlying data fetching scripts

    • Check: which python3
    • Version: 3.6 or later
  2. JIRA Authentication: Environment variables must be configured for bug data

    • JIRA_URL: Your JIRA instance URL
    • JIRA_API_TOKEN: Your Jira API token
    • JIRA_USERNAME: Your Jira email address
    • See /teams:health-check-jiras for setup instructions
  3. Network Access: Must be able to reach both component health API and JIRA

    • Ensure HTTPS requests can be made to both services
    • Check firewall and VPN settings if needed

Notes

  • CRITICAL: This command AUTOMATICALLY fetches data from TWO sources:
    1. Regression API (via /teams:health-check-regressions)
    2. JIRA API (via /teams:health-check-jiras)
  • Both data sources are REQUIRED and fetched automatically without user prompting
  • The analysis is incomplete without both regression and bug data
  • Health grades are subjective and intended as guidance, not criticism
  • Recommendations focus on actionable items (open untriaged regressions, not closed)
  • Infrastructure regressions are automatically filtered from regression counts
  • JIRA queries default to open bugs + bugs closed in last 30 days
  • HTML reports provide interactive visualizations combining both data sources with clickable JIRA links for all bug counts
  • If one data source fails, the command continues with the available data and notes the failure
  • For detailed regression data only, use /teams:list-regressions
  • For detailed JIRA data only, use /teams:list-jiras
  • This command provides the most comprehensive view by combining both sources

See Also

  • Related Command: /teams:health-check-regressions (regression metrics)
  • Related Command: /teams:health-check-jiras (bug backlog metrics)
  • Related Command: /teams:list-regressions (raw regression data)
  • Related Command: /teams:list-jiras (raw JIRA data)
  • Skill Documentation: plugins/teams/skills/analyze-regressions/SKILL.md
  • Script: plugins/teams/skills/list-regressions/list_regressions.py
  • Script: plugins/teams/skills/summarize-jiras/summarize_jiras.py

Name

teams:list-components

Synopsis

/teams:list-components [--team <team-name>]

Description

The teams:list-components command displays all OCPBUGS component names, with optional filtering by team.

This command is useful for:

  • Discovering available OCPBUGS components
  • Discovering OCPBUGS components for a specific team
  • Validating OCPBUGS component names before filing or querying bugs
  • Understanding which components are tracked in OCPBUGS per team
  • Finding exact component names for use in JIRA queries

Implementation

  1. Verify Working Directory

    • Ensure you are in the repository root directory
    • Run pwd to confirm
  2. Run the list-components Script

    • For all components: python3 plugins/teams/skills/list-components/list_components.py
    • For team components: python3 plugins/teams/skills/list-components/list_components.py --team "API Server"
    • Team names must match exactly (case-sensitive)
  3. Parse and Display Results

    • Script outputs JSON with total_components, components array, and optional team field

Examples

  1. List all OCPBUGS components:

    /teams:list-components
    
  2. List OCPBUGS components for a specific team:

    /teams:list-components --team "API Server"
    

Arguments

  • --team (optional): Filter components by team name
    • Use /teams:list-teams to get available team names
    • Example: --team "API Server"

Prerequisites

  • Python 3.6 or later

Notes

  • Only OCPBUGS components are returned
  • Team names are case-sensitive - use /teams:list-teams to get correct names
  • Typical count: ~87 total components across 29 teams
  • Reads from committed mapping file (no download needed)

Data Source

The team and component mapping data originates from:

If data looks wrong or missing:

  1. Submit a PR to https://gitlab.cee.redhat.com/hybrid-platforms/org to correct the source data
  2. After the PR merges, regenerate the mapping file in this repository:
    python3 plugins/teams/generate_team_component_map.py
    
  3. Commit the updated team_component_map.json file

See Also

  • Skill: plugins/teams/skills/list-components/SKILL.md
  • Related Command: /teams:list-teams
  • Mapping File: plugins/teams/team_component_map.json
  • Generator Script: plugins/teams/generate_team_component_map.py

Name

teams:list-jiras

Synopsis

/teams:list-jiras <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]

Description

The teams:list-jiras command queries JIRA bugs for a specified project and returns raw issue data. It fetches JIRA issues with all their fields and metadata without performing any summarization or aggregation.

By default, the command includes:

  • All currently open bugs
  • Bugs closed in the last 30 days (to track recent closure activity)

This command is useful for:

  • Fetching raw JIRA issue data for further processing
  • Accessing complete issue details including all fields
  • Building custom analysis workflows
  • Providing data to other commands (like summarize-jiras)
  • Exporting JIRA data for offline analysis

Implementation

  1. Verify Prerequisites: Check that Python 3 is installed

    • Run: python3 --version
    • Verify version 3.6 or later is available
  2. Verify Environment Variables: Ensure JIRA authentication is configured

    • Check that the following environment variables are set:

      • JIRA_URL: Base URL for JIRA instance (e.g., "https://redhat.atlassian.net")
      • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
      • JIRA_API_TOKEN: Your JIRA API token
    • Verify with:

      echo "JIRA_URL: ${JIRA_URL}"
      echo "JIRA_USERNAME: ${JIRA_USERNAME}"
      echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+***set***}"
      
    • If missing, guide the user to set them:

      export JIRA_URL="https://redhat.atlassian.net"
      export JIRA_USERNAME="your-email@redhat.com"
      export JIRA_API_TOKEN="your-api-token-here"
      
  3. Parse Arguments: Extract project key and optional filters from arguments

    • Project key: Required first argument (e.g., "OCPBUGS", "OCPSTRAT")
    • Optional filters:
      • --component: Space-separated list of component search strings (fuzzy match)
      • --status: Space-separated list of status values
      • --include-closed: Flag to include closed bugs
      • --limit: Maximum number of issues to fetch per component (default: 1000, max: 1000)
  4. Resolve Component Names (if component filter provided): Use fuzzy matching to find actual component names

    • Extract release from context or ask user for release version
    • Run list_components.py to get all available components:
      python3 plugins/component-health/skills/list-components/list_components.py --release <release>
      
    • For each search string in --component:
      • Find all components containing that string (case-insensitive)
      • Combine all matches into a single list
      • Remove duplicates
      • If no matches found for a search string, warn the user and show available components
  5. Execute Python Script: Run the list_jiras.py script for each component

    • Script location: plugins/component-health/skills/list-jiras/list_jiras.py
    • Important: Iterate over each resolved component separately to avoid overly large queries
    • For each component:
      • Build command with project, single component, and other filters
      • Execute: python3 list_jiras.py --project <project> --component "<component>" [other args]
      • Capture JSON output from stdout
    • Aggregate results from all components into a combined response
  6. Parse Output: Process the aggregated JSON response

    • Extract metadata:
      • project: Project key queried
      • total_count: Total matching issues in JIRA
      • fetched_count: Number of issues actually fetched
      • query: JQL query that was executed
      • filters: Applied filters
    • Extract raw issues array:
      • issues: Array of complete JIRA issue objects with all fields
  7. Present Results: Display or store the raw JIRA data

    • Show which components were matched (if fuzzy search was used)
    • The command returns the aggregated JSON response with metadata and raw issues from all components
    • Inform the user about total count vs fetched count per component
    • The raw issue data can be passed to other commands for analysis
    • Suggest using /teams:summarize-jiras for summary statistics
    • Highlight any truncation (if fetched_count < total_count for any component)
    • Suggest increasing --limit if results are truncated
  8. Error Handling: Handle common error scenarios

    • Network connectivity issues
    • Invalid JIRA credentials
    • Invalid project key
    • HTTP errors (401, 404, 500, etc.)
    • Rate limiting (429)

Return Value

The command outputs raw JIRA issue data in JSON format with the following structure:

Metadata

  • project: JIRA project key that was queried
  • total_count: Total number of matching issues in JIRA
  • fetched_count: Number of issues actually fetched (may be less than total if limited)
  • query: JQL query that was executed (includes filters)
  • filters: Object containing applied filters:
    • components: List of component filters or null
    • statuses: List of status filters or null
    • include_closed: Boolean indicating if closed bugs were included
    • limit: Maximum number of issues fetched

Issues Array

  • issues: Array of raw JIRA issue objects, each containing:
    • key: Issue key (e.g., "OCPBUGS-12345")
    • fields: Object containing all issue fields:
      • summary: Issue title/summary
      • status: Status object with name and ID
      • priority: Priority object with name and ID
      • components: Array of component objects
      • assignee: Assignee object with user details
      • created: Creation timestamp
      • updated: Last updated timestamp
      • resolutiondate: Resolution timestamp (if closed)
      • versions: Affects Version/s array
      • fixVersions: Fix Version/s array
      • customfield_10855: Target Version (custom field)
      • And other JIRA fields as applicable

Additional Information

  • note: (Optional) If results are truncated, includes a note suggesting to increase the limit
  • component_queries: (Optional) When multiple components are queried, this array shows the individual query executed for each component. Each entry contains:
    • component: The component name
    • query: The JQL query executed for this component
    • total_count: Total matching issues for this component
    • fetched_count: Number of issues fetched for this component

Example Output Structure

{
  "project": "OCPBUGS",
  "total_count": 1500,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "component_queries": [
    {
      "component": "kube-apiserver",
      "query": "project = OCPBUGS AND component = \"kube-apiserver\" AND ...",
      "total_count": 800,
      "fetched_count": 50
    },
    {
      "component": "kube-controller-manager",
      "query": "project = OCPBUGS AND component = \"kube-controller-manager\" AND ...",
      "total_count": 700,
      "fetched_count": 50
    }
  ],
  "issues": [
    {
      "key": "OCPBUGS-12345",
      "fields": {
        "summary": "Bug title here",
        "status": {"name": "New", "id": "1"},
        "priority": {"name": "Major", "id": "3"},
        "components": [{"name": "kube-apiserver"}],
        "created": "2025-11-01T10:30:00.000+0000",
        ...
      }
    },
    ...
  ],
  "note": "Showing first 100 of 1500 total results. Increase --limit for more data."
}

Examples

  1. List all open bugs for a project:

    /teams:list-jiras OCPBUGS
    

    Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and returns raw issue data.

  2. Filter by specific component (exact match):

    /teams:list-jiras OCPBUGS --component "kube-apiserver"
    

    Returns raw data for bugs in the kube-apiserver component only.

  3. Filter by fuzzy search:

    /teams:list-jiras OCPBUGS --component network
    

    Finds all components containing "network" (case-insensitive) and returns bugs for all matches (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.). Makes separate JIRA queries for each component and aggregates results.

  4. Filter by multiple search strings:

    /teams:list-jiras OCPBUGS --component etcd kube-
    

    Finds all components containing "etcd" OR "kube-" and returns combined bug data. Iterates over each component separately to avoid overly large queries.

  5. Include closed bugs:

    /teams:list-jiras OCPBUGS --include-closed --limit 500
    

    Returns both open and closed bugs, fetching up to 500 issues per component.

  6. Filter by status:

    /teams:list-jiras OCPBUGS --status New "In Progress" Verified
    

    Returns only bugs in New, In Progress, or Verified status.

  7. Combine fuzzy search with other filters:

    /teams:list-jiras OCPBUGS --component network --status New Assigned --limit 200
    

    Returns bugs for all networking components that are in New or Assigned status.

Arguments

  • $1 (required): JIRA project key

    • Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
    • Must be a valid JIRA project you have access to
  • $2+ (optional): Filter flags

    • --component <search1> [search2 ...]: Filter by component names using fuzzy search

      • Space-separated list of component search strings
      • Case-insensitive substring matching
      • Each search string matches all components containing that substring
      • Makes separate JIRA queries for each matched component to avoid overly large results
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
      • Note: Requires release context (inferred from recent commands or specified by user)
    • --status <status1> [status2 ...]: Filter by status values

      • Space-separated list of status names
      • Examples: New, "In Progress", Verified, Modified, ON_QA
    • --include-closed: Include closed bugs in results

      • By default, only open bugs are returned
      • When specified, closed bugs are included
    • --limit <N>: Maximum number of issues to fetch per component

      • Default: 1000
      • Range: 1-1000
      • When using component filters, this limit applies to each component separately
      • Higher values provide more accurate statistics but slower performance

Prerequisites

  1. Python 3: Required to run the data fetching script

    • Check: which python3
    • Version: 3.6 or later
  2. JIRA Authentication: Environment variables must be configured

    • JIRA_URL: Your JIRA instance URL
    • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
    • JIRA_API_TOKEN: Your JIRA API token

    How to get a JIRA API token:

  3. Network Access: Must be able to reach your JIRA instance

    • Ensure HTTPS requests can be made to JIRA_URL
    • Check firewall and VPN settings if needed

Notes

  • The script uses Python's standard library only (no external dependencies)
  • Output is JSON format for easy parsing and further processing
  • Diagnostic messages are written to stderr, data to stdout
  • The script has a 30-second timeout for HTTP requests
  • For large projects, use component filters to reduce query size
  • The returned data includes ALL JIRA fields for each issue, providing complete information
  • If you need summary statistics, use /teams:summarize-jiras instead
  • If results show truncation, increase the --limit parameter to fetch more issues

See Also

  • Skill Documentation: plugins/component-health/skills/list-jiras/SKILL.md
  • Script: plugins/component-health/skills/list-jiras/list_jiras.py
  • Related Command: /teams:summarize-jiras (for summary statistics)
  • Related Command: /teams:analyze

Name

teams:list-regressions

Synopsis

/teams:list-regressions <view> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]

Description

The teams:list-regressions command fetches regression data for a specified view (e.g., "4.22-main") and returns raw regression details without performing any summarization or analysis. A view represents a specific regression tracking context within a release — multiple views can exist per release. The release is derived from the view name automatically. Open/closed status for each regression is determined by the view's own tracking (not the regression's global status). It provides complete regression information including test names, timestamps, triages, and metadata.

This command is useful for:

  • Fetching raw regression data for further processing
  • Accessing complete regression details for specific components
  • Building custom analysis workflows
  • Providing data to other commands (like summarize-regressions and analyze)
  • Exporting regression data for offline analysis
  • Investigating specific test failures across releases

Implementation

  1. Verify Prerequisites: Check that Python 3 is installed

    • Run: python3 --version
    • Verify version 3.6 or later is available
  2. Parse Arguments: Extract view name and optional filters from arguments

    • View format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
    • The release is derived from the view name (e.g., "4.22" from "4.22-main")
    • Optional filters:
      • --components: Space-separated list of component search strings (fuzzy match)
      • --start: Start date for filtering (YYYY-MM-DD)
      • --end: End date for filtering (YYYY-MM-DD)
      • --short: Exclude regression arrays from output (only summaries)
  3. Resolve Component Names: Use fuzzy matching to find actual component names

    • Run list_components.py to get all available components:
      python3 plugins/teams/skills/list-components/list_components.py --release <release>
      
    • If --components was provided:
      • For each search string, find all components containing that string (case-insensitive)
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Combine all matches into a single list
      • Remove duplicates
      • If no matches found for a search string, warn the user and show available components
    • If --components was NOT provided:
      • Use all available components from the list
  4. Fetch Release Dates (if date filtering needed): Run the get_release_dates.py script

    • Script location: plugins/teams/skills/get-release-dates/get_release_dates.py
    • Pass release as --release argument
    • Extract development_start and ga dates from JSON output
    • Use these dates for --start and --end parameters if not explicitly provided
  5. Execute Python Script: Run the list_regressions.py script

    • Script location: plugins/teams/skills/list-regressions/list_regressions.py
    • Pass view as --view argument (the script derives the release internally)
    • Pass resolved component names as --components argument
    • Pass --start date if filtering by start date
    • Pass --end date if filtering by end date
    • Capture JSON output from stdout
  6. Parse Output: Process the JSON response

    • The script outputs JSON with the following structure:
      • summary: Overall statistics (total, triaged, percentages, timing metrics)
      • components: Dictionary mapping component names to regression data
        • Each component has:
          • summary: Component-specific statistics
          • open: Array of open regression objects
          • closed: Array of closed regression objects
    • Note: When using --short flag, regression arrays are excluded (only summaries)
  7. Present Results: Display or store the raw regression data

    • Show which components were matched (if fuzzy search was used)
    • The command returns the complete JSON response with metadata and raw regressions
    • Inform the user about overall counts from the summary
    • The raw regression data can be passed to other commands for analysis
    • Suggest using /teams:summarize-regressions for summary statistics
    • Suggest using /teams:analyze for health grading
  8. Error Handling: Handle common error scenarios

    • Network connectivity issues
    • Invalid release format
    • API errors (404, 500, etc.)
    • Empty results
    • No matches for component filter

Return Value

The command outputs raw regression data in JSON format with the following structure:

Overall Summary

  • summary.total: Total number of regressions
  • summary.triaged: Total number of regressions triaged to JIRA bugs
  • summary.triage_percentage: Percentage of regressions that have been triaged
  • summary.filtered_suspected_infra_regressions: Count of infrastructure regressions filtered
  • summary.time_to_triage_hrs_avg: Average hours from opened to first triage
  • summary.time_to_triage_hrs_max: Maximum hours from opened to first triage
  • summary.time_to_resolve_hrs_avg: Average hours from opened to triage resolved (closed triaged regressions only)
  • summary.time_to_resolve_hrs_max: Maximum hours from opened to triage resolved (closed triaged regressions only)
  • summary.open: Summary statistics for open regressions
    • total: Number of open regressions
    • triaged: Number of open regressions triaged
    • triage_percentage: Percentage of open regressions triaged
    • time_to_triage_hrs_avg, time_to_triage_hrs_max: Triage timing metrics
    • open_hrs_avg, open_hrs_max: How long regressions have been open
  • summary.closed: Summary statistics for closed regressions
    • total: Number of closed regressions
    • triaged: Number of closed regressions triaged
    • triage_percentage: Percentage of closed regressions triaged
    • time_to_triage_hrs_avg, time_to_triage_hrs_max: Triage timing metrics
    • time_to_resolve_hrs_avg, time_to_resolve_hrs_max: Time to resolve metrics (regression opened to triage resolved)

Per-Component Data

  • components: Dictionary mapping component names to objects containing:
    • summary: Component-specific statistics (same structure as overall summary)
    • open: Array of open regression objects
    • closed: Array of closed regression objects

Regression Object Structure

Each regression object (in components.*.open or components.*.closed arrays) contains:

  • id: Unique regression identifier
  • view: Release view (e.g., "4.21-main")
  • release: Release version
  • base_release: Base release for comparison
  • component: Component name
  • capability: Test capability/area
  • test_name: Full test name
  • variants: Array of test variants where regression occurred
  • opened: Timestamp when regression was first detected
  • closed: Timestamp when regression was closed (null if still open)
  • triages: Array of triage objects (JIRA bugs linked to this regression)
    • Each triage has jira_key, created_at, url fields
  • last_failure: Timestamp of most recent test failure
  • max_failures: Maximum number of failures detected

Example Output Structure

{
  "summary": {
    "total": 62,
    "triaged": 59,
    "triage_percentage": 95.2,
    "filtered_suspected_infra_regressions": 8,
    "time_to_triage_hrs_avg": 68,
    "time_to_triage_hrs_max": 240,
    "time_to_resolve_hrs_avg": 168,
    "time_to_resolve_hrs_max": 480,
    "open": { "total": 2, "triaged": 1, ... },
    "closed": { "total": 60, "triaged": 58, ... }
  },
  "components": {
    "Monitoring": {
      "summary": {
        "total": 15,
        "triaged": 13,
        "triage_percentage": 86.7,
        ...
      },
      "open": [
        {
          "id": 12894,
          "component": "Monitoring",
          "test_name": "[sig-instrumentation] Prometheus ...",
          "opened": "2025-10-15T10:30:00Z",
          "closed": null,
          "triages": [],
          ...
        }
      ],
      "closed": [...]
    },
    "etcd": {
      "summary": { "total": 20, "triaged": 19, ... },
      "open": [],
      "closed": [...]
    }
  }
}

Note: When using --short flag, the open and closed arrays are excluded from component objects to reduce response size.

Examples

  1. List all regressions for a view:

    /teams:list-regressions 4.17-main
    

    Fetches all regression data for the 4.17-main view, including all components.

  2. Filter by specific component (exact match):

    /teams:list-regressions 4.21-main --components Monitoring
    

    Returns regression data for only the Monitoring component.

  3. Filter by fuzzy search:

    /teams:list-regressions 4.21-main --components network
    

    Finds all components containing "network" (case-insensitive):

    • Networking / ovn-kubernetes
    • Networking / DNS
    • Networking / router
    • Networking / cluster-network-operator
    • ... and returns regression data for all matches
  4. Filter by multiple search strings:

    /teams:list-regressions 4.21-main --components etcd kube-
    

    Finds all components containing "etcd" OR "kube-":

    • Etcd
    • kube-apiserver
    • kube-controller-manager
    • kube-scheduler
    • kube-storage-version-migrator
  5. Filter by development window (GA'd release):

    /teams:list-regressions 4.17-main --start 2024-05-17 --end 2024-10-29
    

    Fetches regressions within the development window:

    • Excludes regressions closed before 2024-05-17
    • Excludes regressions opened after 2024-10-29
  6. Filter for in-development release:

    /teams:list-regressions 4.22-main --start 2025-09-02
    

    Fetches regressions for an in-development release view:

    • Excludes regressions closed before development started
    • No end date (release still in development)
  7. Combine fuzzy component search and date filters:

    /teams:list-regressions 4.21-main --components network --start 2025-09-02
    

    Returns regressions for all networking components from the development window.

Arguments

  • $1 (required): View name

    • Format: "X.Y-suffix" (e.g., "4.22-main", "4.17-main")
    • The release is derived from the view name (e.g., "4.22" from "4.22-main")
    • Multiple views can exist per release (e.g., "4.22-main", "4.22-main-mass-failure")
  • $2+ (optional): Filter flags

    • --components <search1> [search2 ...]: Filter by component names using fuzzy search

      • Space-separated list of component search strings
      • Case-insensitive substring matching
      • Each search string matches all components containing that substring
      • If no components provided, all components are analyzed
      • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
      • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
    • --start <YYYY-MM-DD>: Filter regressions by start date

      • Excludes regressions closed before this date
      • Typically the development_start date from release metadata
    • --end <YYYY-MM-DD>: Filter regressions by end date

      • Excludes regressions opened after this date
      • Typically the GA date for released versions
      • Omit for in-development releases
    • --short: Exclude regression arrays from output

      • Only include summary statistics
      • Significantly reduces response size for large datasets
      • Use when you only need counts and metrics, not individual regressions

Prerequisites

  1. Python 3: Required to run the data fetching script

    • Check: which python3
    • Version: 3.6 or later
  2. Network Access: Must be able to reach the component health API

    • Ensure HTTPS requests can be made
    • Check firewall and VPN settings if needed
  3. API Configuration: The API endpoint must be configured in the script

    • Location: plugins/teams/skills/list-regressions/list_regressions.py
    • The script should have the correct API base URL

Notes

  • The script uses Python's standard library only (no external dependencies)
  • Output is JSON format for easy parsing and further processing
  • Diagnostic messages are written to stderr, data to stdout
  • The script has a 30-second timeout for HTTP requests
  • For large result sets, use component filters or the --short flag to reduce output size
  • Date filtering helps focus on relevant regressions within the development window
  • Infrastructure regressions (closed quickly on high-volume days) are automatically filtered
  • The returned data includes complete regression information, not summaries
  • If you need summary statistics, use /teams:summarize-regressions instead
  • If you need health grading, use /teams:analyze instead

See Also

  • Skill Documentation: plugins/teams/skills/list-regressions/SKILL.md
  • Script: plugins/teams/skills/list-regressions/list_regressions.py
  • Related Command: /teams:summarize-regressions (for summary statistics)
  • Related Command: /teams:analyze (for health grading and analysis)
  • Related Skill: get-release-dates (for fetching development window dates)

Name

teams:list-teams

Synopsis

/teams:list-teams

Description

The teams:list-teams command displays all team names from the team component mapping.

Note: The underlying script returns rich team data (components, description, repos, team_size, slack_channels), but this command presents only a concise list of team names. The full team data is available to the AI agent for context but should not be displayed to the user unless specifically requested.

This command is useful for:

  • Discovering available teams
  • Validating team names before using them in other commands
  • Finding team names for use with /teams:list-components --team or /teams:health-check --team

Implementation

  1. Verify Working Directory

    • Ensure you are in the repository root directory
  2. Run the list-teams Script

    • python3 plugins/teams/skills/list-teams/list_teams.py
  3. Parse and Display Results

    • Script outputs JSON with total_teams and teams object/array
    • New format (after regeneration): teams is a dictionary mapping team names to team info objects containing:
      • components: Array of OCPBUGS component names
      • description: Team description
      • team_size: Number of team members
      • repos: Array of repository names
      • slack_channels: Array of Slack channel names (forum type only)
    • Old format (before regeneration): teams is a simple array of team names
    • Display to user: Only show team names in a concise list format, regardless of which format is returned
    • Use internally: Full team data is available for context and can be used to answer follow-up questions

Examples

  1. List all teams:
    /teams:list-teams
    

Arguments

None

Prerequisites

  • Python 3.6 or later

Notes

  • Team names are case-sensitive
  • Returns only teams with OCPBUGS components
  • Typical count: ~29 teams
  • Reads from committed mapping file (no download needed)

Data Source

The team and component mapping data originates from:

If data looks wrong or missing:

  1. Submit a PR to https://gitlab.cee.redhat.com/hybrid-platforms/org to correct the source data
  2. After the PR merges, regenerate the mapping file in this repository:
    python3 plugins/teams/generate_team_component_map.py
    
  3. Commit the updated team_component_map.json file

See Also

  • Skill: plugins/teams/skills/list-teams/SKILL.md
  • Related Commands: /teams:list-components, /teams:health-check
  • Mapping File: plugins/teams/team_component_map.json
  • Generator Script: plugins/teams/generate_team_component_map.py

Sponsors

Details

Marketplace
openshift-eng/ai-helpers
Source
plugins/teams
Category
Productivity
Keywords
teams, health, org-structure

More from openshift-eng/ai-helpers

All 56