Implementation guide for creating well-formed Jira bug reports
Inherits all available tools
Additional assets for this skill
This 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