gh-openshift-eng-ai-helpers-plugins-jira/commands/grooming.md

description: Analyze new bugs and cards added over a time period and generate grooming meeting agenda argument-hint: [project-filter] [time-period] [--component component-name] [--label label-name] [--type issue-type]

Name

jira:grooming

Synopsis

/jira:grooming [project-filter] [time-period] [--component component-name] [--label label-name] [--type issue-type]

Description

The jira:grooming command helps teams prepare for backlog grooming meetings. It automatically collects bugs and user stories created within a specified time period OR assigned to a specific sprint, analyzes their priority, complexity, and dependencies, and generates structured grooming meeting agendas.

This command is particularly useful for:

• Backlog organization before sprint planning
• Sprint-specific grooming sessions
• Regular requirement grooming meetings
• Priority assessment of new bugs
• Technical debt organization and planning

Key Features

• Automated Data Collection – Collect and categorize issues within specified time periods or sprints by type (Bug, Story, Task, Epic), extract key information (priority, components, labels), and identify unassigned or incomplete issues.

• Intelligent Analysis – Evaluate issue complexity based on historical data, identify related or duplicate issues, analyze business value and technical impact, and detect potential dependencies.

• Agenda Generation – Build a structured, actionable meeting outline organized by priority and type, with discussion points, decision recommendations, estimation references, and risk alerts.

Implementation

The jira:grooming command runs in three main phases:

🧩 Phase 1: Data Collection

• Automatically queries JIRA for issues based on the provided time range or sprint name:
  • Time range mode: Filters issues by creation date within the specified period (e.g., last-week, 2024-01-01:2024-01-31)
  • Sprint mode: Filters issues by JIRA Sprint without time constraints (e.g., "OTA 277")
  • Sprint detection: If the time-period parameter doesn't match known time range formats, it's treated as a sprint name
• Supports complex JQL filters, including multi-project, component-based, label-based, and issue-type queries.
• Extracts key fields such as title, type, priority, component, reporter, and assignee.
• Detects related or duplicate issues to provide better context.

🧠 Phase 2: Analysis & Processing

• Groups collected issues by type and priority (e.g., Critical Bugs, High Priority Stories).
• Identifies incomplete or unclear issues that need clarification.
• Estimates complexity and effort based on similar historical data.
• Highlights risks, dependencies, and recommended next actions.

📋 Phase 3: Report Generation

• Automatically generates a structured grooming meeting agenda in Markdown format.
• Includes discussion points, decision checklists, and action items.
• Output can be copied directly into Confluence or shared with the team.

Usage Examples

1. Single project weekly review:

   /jira:grooming OCPSTRAT last-week
   

2. Multiple OpenShift projects:

   /jira:grooming "OCPSTRAT,OCPBUGS,HOSTEDCP" last-2-weeks
   

3. Filter by component:

   /jira:grooming OCPSTRAT last-week --component "Control Plane"
   

4. Custom date range:

   /jira:grooming OCPBUGS 2024-10-01:2024-10-15
   

5. Filter by label:

   /jira:grooming OCPSTRAT last-week --label "technical-debt"
   

6. Combine component and label filters:

   /jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance"
   

7. Query sprint issues with component filter:

   /jira:grooming OCPBUGS "OTA 277" --component "Cluster Version Operator"
   

8. Filter by issue type:

   /jira:grooming OCPSTRAT last-week --type Bug
   

9. Filter by multiple issue types:

   /jira:grooming OCPSTRAT last-week --type "Bug,Epic"
   

10. Combine all filters:

    /jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance" --type Story
    

Output Format

Grooming Meeting Agenda

The command outputs a ready-to-use Markdown document that can be copied into Confluence or shared with your team.

# Backlog Grooming Agenda
**Project**: [project-key] | **Period**: [time-period] | **New Issues**: [count]

## 🚨 Critical Issues ([count])
- **[PROJ-1234]** System crashes on login - *Critical, needs immediate attention*
- **[PROJ-1235]** Performance degradation - *High, assign to team lead*

## 📈 High Priority Stories ([count])  
- **[PROJ-1236]** User profile enhancement - *Ready for sprint*
- **[PROJ-1237]** Payment integration - *Needs design review*

## 📝 Needs Clarification ([count])
- **[PROJ-1238]** Missing acceptance criteria
- **[PROJ-1239]** Unclear technical requirements

## 📋 Action Items
- [ ] Assign PROJ-1234 to senior developer (immediate)
- [ ] Schedule design review for PROJ-1237 (this week)
- [ ] Clarify requirements for PROJ-1238,1239 (before next grooming)

Configuration

Default Query Configuration (.jira-grooming.json)

{
  "defaultProjects": ["OCPSTRAT", "OCPBUGS"],
  "defaultLabels": [],
  "priorityMapping": {
    "Critical": "🚨 Critical",
    "High": "📈 High Priority"
  },
  "estimationReference": {
    "enableHistoricalComparison": true
  }
}

Arguments

• $1 – project-filter
  JIRA project selector. Supports single or multiple projects (comma-separated).
  Examples:

  • OCPSTRAT
  • "OCPSTRAT,OCPBUGS,HOSTEDCP"
  • "OpenShift Virtualization,Red Hat OpenShift Control Planes"
    Default: read from configuration file

• $2 – time-period Time range for issue collection OR sprint name. Options:

  • Time ranges: last-week | last-2-weeks | last-month | YYYY-MM-DD:YYYY-MM-DD
  • Sprint name: Any string that doesn't match time range formats (e.g., "OTA 277") Default: last-week

  Behavior:

  • If a time range is provided, filters issues by creation date within that range
  • If a sprint name is provided, filters issues by JIRA Sprint WITHOUT applying time range constraints

• --component (optional) Filter by JIRA component (single or comma-separated). Examples:

  • --component "Networking"
  • --component "Control Plane,Storage"

• --label (optional) Filter by JIRA labels (single or comma-separated). Examples:

  • --label "technical-debt"
  • --label "performance,security"

• --type (optional) Filter by JIRA issue type (single or comma-separated). Examples:

  • --type Bug
  • --type "Epic,Story"
  • --type "Bug,Task,Feature"

  Common issue types: Bug, Story, Task, Epic, Feature, Sub-task

Return Value

• Markdown Report: Ready-to-use grooming agenda with categorized issues and action items

See Also

• jira:status-rollup - Status rollup reports
• jira:solve - Issue solution generation