openshift-eng/create-bug

Create Jira Bug

This skill provides implementation guidance for creating well-structured Jira bug reports with complete reproduction steps and clear problem descriptions.

When to Use This Skill

This skill is automatically invoked by the /jira:create bug command to guide the bug creation process.

Prerequisites

• MCP Jira server configured and accessible
• User has permissions to create issues in the target project
• Bug information available (problem description, steps to reproduce, etc.)

Reference Documentation:

• Markdown for Jira Reference - Markdown formatting for Jira descriptions

Custom Fields (redhat.atlassian.net)

| Field | ID | Type | Usage | |-------|------|------|-------| | Epic Link | customfield_10014 | String | Links Bug to parent Epic. Value = Epic issue key | | Target Version | customfield_10855 | Array | Format: [{"id": "VERSION_ID"}] |

Parent Linking Fallback

If creation fails with a 4xx error that specifically references customfield_10014 or customfield_10018 in the error response:

1. Duplicate guard: Search for an issue with the same summary in the target project before retrying — if one exists, the original call may have partially succeeded
2. Retry WITHOUT the parent/epic link field
3. After creation succeeds, add the link via editJiraIssue (include contentFormat: "markdown")

Bug Report Best Practices

Complete Information

A good bug report contains:

1. Clear summary - Brief description that identifies the problem
2. Detailed description - Complete context and background
3. Reproducibility - How often the bug occurs
4. Steps to reproduce - Exact sequence to trigger the bug
5. Actual vs expected results - What happens vs what should happen
6. Environment details - Version, platform, configuration
7. Additional context - Logs, screenshots, error messages

Summary Guidelines

The summary should:

• Be concise (one sentence)
• Identify the problem clearly
• Include key context when helpful
• Avoid vague terms like "broken" or "doesn't work"

Good examples:

• "API server returns 500 error when creating namespaces"
• "Control plane pods crash on upgrade from 4.20 to 4.21"
• "Memory leak in etcd container after 24 hours"

Bad examples:

• "Things are broken"
• "Error in production"
• "Fix the bug"

Bug Description Template

Use this template structure for consistency:

Description of problem:
<Clear, detailed description of the issue>

Version-Release number of selected component (if applicable):
<e.g., 4.21.0, openshift-client-4.20.5>

How reproducible:
<Always | Sometimes | Rarely>

Steps to Reproduce:
1. <First step - be specific>
2. <Second step>
3. <Third step>

Actual results:
<What actually happens - include error messages>

Expected results:
<What should happen instead>

Additional info:
<Logs, screenshots, stack traces, related issues, workarounds>

Interactive Bug Collection Workflow

When creating a bug, guide the user through each section interactively:

1. Problem Description

Prompt: "What is the problem? Describe it clearly and in detail."

Tips to share:

• Provide context: What were you trying to do?
• Be specific: What component or feature is affected?
• Include impact: Who is affected? How severe is it?

Example response:

The kube-apiserver pod crashes immediately after upgrading a hosted control plane cluster from version 4.20 to 4.21. The pod enters CrashLoopBackOff state and all API requests to the cluster fail.

2. Version Information

Prompt: "Which version exhibits this issue? (e.g., 4.21.0, 4.20.5)"

Tips:

• Include full version number if known
• Specify component version if different from platform version
• Note if issue affects multiple versions

Default: Use project-specific default (e.g., 4.21 for OCPBUGS)

3. Reproducibility

Prompt: "How reproducible is this issue?"

Options:

• Always - Happens every time following the steps
• Sometimes - Happens intermittently, even with same steps
• Rarely - Hard to reproduce, happened once or few times

Use case for each:

• Always: Easiest to debug and fix
• Sometimes: May be timing-related or race condition
• Rarely: May be environmental or complex interaction

4. Steps to Reproduce

Prompt: "What are the exact steps to reproduce this issue? Be as specific as possible."

Guidelines:

• Number each step
• Be precise (exact commands, button clicks, inputs)
• Include environment setup if needed
• Use code blocks for commands
• Mention any prerequisites

Example:

Steps to Reproduce:
1. Create a ROSA HCP cluster on version 4.20.0:
   rosa create cluster --name test-cluster --version 4.20.0 --hosted-cp
2. Wait for cluster to be fully ready (about 15 minutes)
3. Initiate upgrade to 4.21.0:
   rosa upgrade cluster --cluster test-cluster --version 4.21.0
4. Monitor the control plane pods:
   oc get pods -n clusters-test-cluster -w
5. Observe kube-apiserver pod status

Validation:

• Ensure at least one step is provided
• Check that steps are numbered/ordered
• Verify steps are specific enough to follow

5. Actual Results

Prompt: "What actually happens when you follow those steps?"

Guidelines:

• Describe exactly what occurs
• Include error messages (full text)
• Mention symptoms (crashes, hangs, wrong output)
• Include relevant logs or stack traces
• Note timing (immediate, after 5 minutes, etc.)

Example:

Actual results:
The kube-apiserver pod crashes immediately after the upgrade completes. The pod restarts continuously (CrashLoopBackOff). Error in pod logs:

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x...]

API requests to the cluster fail with:
Error from server: error dialing backend: dial tcp: lookup kube-apiserver: no such host

6. Expected Results

Prompt: "What should happen instead? What is the expected behavior?"

Guidelines:

• Describe the correct behavior
• Be specific about expected state/output
• Contrast with actual results

Example:

Expected results:
The kube-apiserver pod should start successfully after the upgrade. The pod should be in Running state, and API requests to the cluster should succeed normally.

Validation:

• Ensure expected results differ from actual results
• Check that expected behavior is clearly stated

7. Additional Information

Prompt: "Any additional context? (Optional: logs, screenshots, workarounds, related issues)"

Helpful additions:

• Full logs or log excerpts
• Screenshots or recordings
• Stack traces
• Related Jira issues or documentation
• Workarounds discovered
• Impact assessment (severity, affected users)
• Environment specifics (region, network config, etc.)

Example:

Additional info:
- Cluster ID: abc123-def456
- Region: us-east-1
- Full pod logs attached: kube-apiserver.log
- Related issue: OCPBUGS-12340 (similar crash in 4.19→4.20 upgrade)
- Workaround: Rollback to 4.20.0 and cluster recovers
- Affects all ROSA HCP clusters in production

Component and Version Handling

Auto-Detection

Analyze the bug description for component hints:

• Product names: "OpenShift", "ROSA", "ARO", "HyperShift"
• Component names: "API server", "etcd", "networking", "storage"
• Platform: "AWS", "Azure", "GCP", "bare metal"

Version Fields

Different projects may use versions differently:

OCPBUGS:

• Affects Version/s (versions): Version where bug was found
• Target Version (customfield_10855): Version where fix is targeted
• Never set Fix Version/s (fixVersions)

General projects:

• May only have Affects Version/s
• Check project configuration for version fields

Project-Specific Overrides

If bug is for a known project with specific conventions (e.g., CNTRLPLANE/OCPBUGS), the cntrlplane skill will be invoked automatically and will override defaults.

Field Validation

Before submitting the bug, validate:

Required Fields

• ✅ Summary is not empty and is clear
• ✅ Description contains problem description
• ✅ Component is specified (or project doesn't require it)
• ✅ Affects version is specified (if required by project)

Description Quality

• ✅ "Steps to Reproduce" has at least one step
• ✅ "Actual results" is different from "Expected results"
• ✅ "How reproducible" is specified (Always/Sometimes/Rarely)

Security

• ✅ No credentials, API keys, or secrets in any field
• ✅ Logs are sanitized (passwords, tokens redacted)
• ✅ Screenshots don't expose sensitive information

MCP Issue Creation

Create bugs via createJiraIssue with contentFormat: "markdown". Key parameters:

• projectKey: e.g., "OCPBUGS"
• issueTypeName: "Bug"
• summary: concise bug summary
• description: formatted bug template (Markdown)
• additional_fields: custom fields including "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"}, and version fields when a target version is specified

Jira Description Formatting

Use Markdown formatting with contentFormat: "markdown". For formatting reference, see Markdown for Jira Reference.

Error Handling

Missing Required Information

Scenario: User doesn't provide required fields.

Action:

1. Identify missing required fields
2. Prompt user for each missing field
3. Provide context/examples to help
4. Re-validate before submission

Example:

Summary is required but not provided. Please provide a brief summary of the bug:
Example: "API server crashes when creating namespaces"

Invalid Version

Scenario: Specified version doesn't exist in project.

Action:

1. Fetch valid versions via getJiraIssueTypeMetaWithFields (check allowedValues for the versions field)
2. Suggest closest match or list available versions
3. Ask user to confirm or select different version

Example:

Version "4.21.5" not found for project OCPBUGS.
Available versions: 4.19, 4.20, 4.21, 4.22
Did you mean "4.21"?

Component Required But Not Provided

Scenario: Project requires component, but none specified.

Action:

1. Ask user which component the bug affects
2. If available, fetch and display component list for project
3. Accept user's component selection
4. Validate component exists before submission

Security Validation Failure

Scenario: Sensitive data detected in bug content.

Action:

1. STOP submission immediately
2. Inform user what type of data was detected (without echoing it)
3. Provide guidance on redaction
4. Request sanitized version

Example:

I detected what appears to be an API token in the "Steps to Reproduce" section.
Please replace with a placeholder like "YOUR_API_TOKEN" or "<redacted>" before proceeding.

MCP Tool Error

Scenario: MCP tool returns an error when creating the bug.

Action:

1. Parse error message
2. Translate to user-friendly explanation
3. Suggest corrective action
4. Offer to retry

Common errors:

• "Field 'component' is required" → Prompt for component
• "Version not found" → Use version error handling
• "Permission denied" → User may lack project permissions, inform them to contact admin

Examples

Example 1: Simple Bug

Input:

/jira:create bug MYPROJECT "Login button doesn't work on mobile"

Interactive prompts:

What is the problem? Describe it clearly.
> The login button on the mobile app doesn't respond to taps on iOS devices.

Which version exhibits this issue?
> 2.1.0

How reproducible is this issue?
> Always

What are the exact steps to reproduce?
> 1. Open mobile app on iPhone 13 (iOS 16.5)
> 2. Navigate to login screen
> 3. Tap the "Login" button
> 4. Nothing happens

What actually happens?
> The button doesn't respond to taps. No visual feedback, no navigation.

What should happen instead?
> The button should navigate to the credentials input screen when tapped.

Any additional context?
> Works fine on Android. Only affects iOS.

Result:

• Issue created in MYPROJECT
• Type: Bug
• Summary: "Login button doesn't work on mobile"
• Description: Formatted with bug template

Example 2: Bug with Auto-Detection (CNTRLPLANE/OCPBUGS)

Input:

/jira:create bug "ROSA HCP control plane pods crash on upgrade"

Auto-applied (via cntrlplane skill):

• Project: OCPBUGS (default for bugs)
• Component: HyperShift / ROSA (detected from "ROSA HCP")
• Affects Version: 4.21
• Target Version: 4.21
• Labels: ai-generated-jira
• Security: Red Hat Employee

Interactive prompts:

• Bug template sections (same as Example 1)

Result:

• Full bug report created with all CNTRLPLANE conventions applied

Example 3: Bug with All Fields Provided

Input:

/jira:create bug OCPBUGS "etcd pod OOMKilled after 48 hours" --component "HyperShift" --version "4.21"

Minimal prompts:

• Description of problem
• Steps to reproduce
• Actual/expected results
• Additional info

Result:

• Bug created with provided component and version
• Only prompts for description content

Best Practices Summary

1. Clear summaries: One sentence, specific problem
2. Complete steps: Exact sequence to reproduce
3. Specific results: Include error messages and symptoms
4. Sanitize content: Remove all credentials and secrets
5. Add context: Logs, environment details, workarounds
6. Use template: Follow standard bug template structure
7. Validate before submit: Check all required fields populated

Workflow Summary

1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component/version from summary keywords
3. ⚙️ Apply project-specific defaults (if applicable)
4. 💬 Interactively collect bug template sections
5. 🔒 Scan for sensitive data
6. ✅ Validate required fields
7. 📝 Format description with Markdown
8. ✅ Create bug via MCP tool
9. 📤 Return issue key and URL

See Also

• /jira:create - Main command that invokes this skill
• cntrlplane skill - CNTRLPLANE/OCPBUGS specific conventions
• Jira documentation on bug workflows