Implementation guide for creating well-formed Jira bug reports
/plugin marketplace add openshift-eng/ai-helpers/plugin install jira@ai-helpersThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides implementation guidance for creating well-structured Jira bug reports with complete reproduction steps and clear problem descriptions.
This skill is automatically invoked by the /jira:create bug command to guide the bug creation process.
A good bug report contains:
The summary should:
Good examples:
Bad examples:
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>
When creating a bug, guide the user through each section interactively:
Prompt: "What is the problem? Describe it clearly and in detail."
Tips to share:
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.
Prompt: "Which version exhibits this issue? (e.g., 4.21.0, 4.20.5)"
Tips:
Default: Use project-specific default (e.g., 4.21 for OCPBUGS)
Prompt: "How reproducible is this issue?"
Options:
Use case for each:
Prompt: "What are the exact steps to reproduce this issue? Be as specific as possible."
Guidelines:
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:
Prompt: "What actually happens when you follow those steps?"
Guidelines:
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
Prompt: "What should happen instead? What is the expected behavior?"
Guidelines:
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:
Prompt: "Any additional context? (Optional: logs, screenshots, workarounds, related issues)"
Helpful additions:
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
Analyze the bug description for component hints:
Different projects may use versions differently:
OCPBUGS:
versions): Version where bug was foundcustomfield_12319940): Version where fix is targetedfixVersions)General projects:
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.
Before submitting the bug, validate:
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>", # e.g., "OCPBUGS", "MYPROJECT"
summary="<bug summary>",
issue_type="Bug",
description="<formatted bug template>",
components="<component name>", # optional, if required by project
additional_fields={
"versions": [{"name": "<version>"}], # affects version, if supported
# Add other project-specific fields as needed
}
)
mcp__atlassian__jira_create_issue(
project_key="OCPBUGS",
summary="Control plane pods crash on upgrade",
issue_type="Bug",
description="""
h2. Description of problem
Control plane pods crash immediately after upgrading from 4.20 to 4.21.
h2. Version-Release number
4.21.0
h2. How reproducible
Always
h2. Steps to Reproduce
# Create a cluster on 4.20
# Upgrade to 4.21
# Observe control plane pod status
h2. Actual results
Pods enter CrashLoopBackOff state.
h2. Expected results
Pods should start successfully.
h2. Additional info
Logs attached.
""",
components="HyperShift",
additional_fields={
"versions": [{"name": "4.21"}], # affects version
"customfield_12319940": "4.21", # target version
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"} # if required
}
)
Use Jira's native formatting (Wiki markup):
h1. Main Heading
h2. Subheading
h3. Sub-subheading
*bold text*
_italic text_
{{monospace}}
{quote}quoted text{quote}
* Bullet item 1
* Bullet item 2
** Nested bullet
# Numbered item 1
# Numbered item 2
{code}
command line text or code
{code}
{code:java}
// Language-specific syntax highlighting
public class Example {}
{code}
[Link text|http://example.com]
[OCPBUGS-123] // Auto-links to Jira issue
Scenario: User doesn't provide required fields.
Action:
Example:
Summary is required but not provided. Please provide a brief summary of the bug:
Example: "API server crashes when creating namespaces"
Scenario: Specified version doesn't exist in project.
Action:
mcp__atlassian__jira_get_project_versions to fetch valid versionsExample:
Version "4.21.5" not found for project OCPBUGS.
Available versions: 4.19, 4.20, 4.21, 4.22
Did you mean "4.21"?
Scenario: Project requires component, but none specified.
Action:
Scenario: Sensitive data detected in bug content.
Action:
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.
Scenario: MCP tool returns an error when creating the bug.
Action:
Common errors:
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:
Input:
/jira:create bug "ROSA HCP control plane pods crash on upgrade"
Auto-applied (via cntrlplane skill):
Interactive prompts:
Result:
Input:
/jira:create bug OCPBUGS "etcd pod OOMKilled after 48 hours" --component "HyperShift" --version "4.21"
Minimal prompts:
Result:
/jira:create - Main command that invokes this skillcntrlplane skill - CNTRLPLANE/OCPBUGS specific conventions