structured issue creation

Structured Issue Creation

Expert assistance for creating well-structured, comprehensive Jira issues from any context.

When to Use This Skill

User wants to create a Jira issue
User mentions tracking work, bugs, features, or tasks
After implementing code that should be tracked
When discussing a problem that should be documented
User asks to "open a ticket" or "create an issue"

Issue Types and When to Use Them

🐛 Bug

When to use: Something is broken or not working as expected

Required information:

What's broken?
How to reproduce?
Expected vs actual behavior
Environment details

📖 Story

When to use: User-facing feature or capability

Required information:

User persona
What they want to do
Why they want it (business value)
Acceptance criteria

✓ Task

When to use: Work that doesn't fit other types (refactoring, documentation, DevOps)

Required information:

What needs to be done?
Why it's needed
Definition of done

🎯 Epic

When to use: Large body of work that contains multiple stories

Required information:

High-level goal
Scope boundaries
Success metrics

Issue Structure Template

Title (Summary)

Format: [Type] Brief, clear description
Length: < 60 characters
Examples:
User login fails with special characters
Add dark mode toggle to settings
Refactor authentication module for testability

Description

For Bugs

Problem

Brief description of what's broken.

Steps to Reproduce

Go to login page
Enter email with + character
Click submit

Expected Behavior

User should be able to login with any valid email.

Actual Behavior

Error: "Invalid email format"

Environment

Browser: Chrome 120
OS: macOS 14
Version: v2.3.1

Screenshots/Logs

[Attach if available]

Impact

Who is affected and how severely?

Suggested Fix

[Optional] Potential solution or workaround

For Stories

User Story

As a [user type] I want [goal] So that [benefit]

Background/Context

Why we're building this feature.

Acceptance Criteria

Criterion 1
Criterion 2
Criterion 3

Design/Mockups

[Link to designs if available]

Technical Notes

API changes needed
Database changes
Third-party integrations

Out of Scope

What we're NOT doing in this story.

For Tasks

Objective

What needs to be accomplished.

Context

Why this work is needed.

Implementation Details

Step 1
Step 2
Step 3

Definition of Done

Code complete
Tests added
Documentation updated
Reviewed and merged

Priority Guidelines

🔴 Highest (P1)

Production outages
Security vulnerabilities
Data loss scenarios
Blocking other work

🟠 High (P2)

Significant bugs affecting many users
Important features with deadlines
Performance issues

🟡 Medium (P3)

Minor bugs
Feature enhancements
Technical debt

🟢 Low (P4)

Nice-to-have features
Minor improvements
Cosmetic issues

Labels Best Practices

Functional Labels

frontend , backend , api , database
mobile , web , desktop

Technical Labels

performance , security , accessibility
technical-debt , refactoring

Process Labels

needs-design , needs-review , blocked
good-first-issue , help-wanted

Business Labels

customer-request , urgent , quick-win

Creating Issues from Code Context

When creating an issue based on code I've written or changes I've detected:

Analyze the change:

What was added/modified?
What problem does it solve?
What testing is needed?

Determine issue type:

Bug fix? → Bug
New feature? → Story or Task
Refactoring? → Task

Extract details:

Use file names for context
Include code snippets in description
Link to related files

Generate structured content:

Clear, descriptive title
Complete description with context
Appropriate labels and priority

Example: Creating Issue from Code

Context: I just helped implement user authentication

Analysis:

New feature added: OAuth integration
Files modified: auth.js, login.js, config.js
Tests added: auth.test.js

Generated Issue:

Title: Implement OAuth 2.0 authentication for user login

Type: Story

Description:

User Story

As a user I want to login using OAuth providers (Google, GitHub) So that I don't need to create another password

Implementation Details

Added OAuth 2.0 authentication with the following changes:

Modified Files:

src/auth/auth.js - OAuth client integration
src/components/login.js - OAuth login buttons
src/config/config.js - OAuth app credentials

Tests:

tests/auth.test.js - OAuth flow tests

Acceptance Criteria

Security Considerations

OAuth credentials stored in environment variables
PKCE flow used for enhanced security
Token refresh logic implemented

Next Steps

Update user documentation
Security team review
Deploy to staging for testing

Labels: backend , authentication , security , needs-review

Priority: High

Creating Issues from Conversations

When creating an issue from a discussion:

Identify the core request: What does the user actually want?

Ask clarifying questions if needed:

"Is this a bug or a new feature?"
"How urgent is this?"
"Who is affected?"
"Any specific requirements?"

Structure the information: Use appropriate template

Confirm with user: Show them the issue before creating

Linking Related Work

When creating issues, consider:

Parent/Child Relationships

Epic → contains → Stories
Story → contains → Subtasks

Issue Links

Blocks: This issue prevents progress on another
Is blocked by: Cannot proceed until another is done
Relates to: General relationship
Duplicates: Same as another issue
Causes: This issue causes another problem

Example

Epic: User Authentication System ├─ Story: Implement OAuth login │ ├─ Task: Add Google OAuth │ ├─ Task: Add GitHub OAuth │ └─ Task: Update login UI ├─ Story: Add password reset flow └─ Story: Implement 2FA

Quality Checklist

Before creating an issue, verify:

Title is clear: Someone unfamiliar with context understands
Description is complete: All necessary information included
Type is correct: Bug/Story/Task/Epic appropriate
Priority is set: Based on impact and urgency
Labels added: For filtering and organization
Assignee considered: Should someone be assigned now?
Linked issues: Related work connected
Acceptance criteria: Clear definition of done

Common Mistakes to Avoid

❌ Vague Titles

"Fix login" → "User login fails with OAuth when email contains + character"

❌ Missing Context

"Implement feature" → Include user story, requirements, acceptance criteria

❌ No Acceptance Criteria

Add clear, testable conditions for completion

❌ Wrong Issue Type

Refactoring as Bug → Should be Task

❌ Missing Priority

Always set priority based on impact

❌ Kitchen Sink Issues

One issue = one logical unit of work. Split large work into multiple issues.

Workflow Integration

After Writing Code

Me: "I've implemented the user profile feature. Should I create a Jira issue to track this?"

You: "Yes, create a story"

Me: [Analyzes code] "I'll create a story with:

Title: 'Implement user profile with avatar upload'
Description includes implementation details from the code
Acceptance criteria based on what was built
Labels: frontend, backend, user-management
Priority: Medium

Create this issue?"

From Bug Reports

You: "Users report that the app crashes when uploading large files"

Me: "I'll create a bug issue:

Title

App crashes when uploading files > 10MB

Description

[Structured bug template with all details]

Should I also search for similar issues first to avoid duplicates?"

Advanced Features

Issue Templates

If your Jira project has custom templates, I can:

Use project-specific fields
Follow your team's conventions
Match your existing issue style

Bulk Creation

Create multiple related issues at once:

You: "Create issues for the payment integration epic"

Me: "I'll create:

Epic: Payment Integration
Story: Stripe API integration
Story: Payment form UI
Story: Transaction history
Task: Payment testing in sandbox

Proceed with all 5 issues?"

How I'll Help

When you need to create an issue, I will:

Gather context: Understand what you want to track
Determine type: Bug, Story, Task, or Epic?
Structure content: Use appropriate template
Add metadata: Priority, labels, relationships
Show preview: Let you review before creating
Create issue: Use /jira-create command
Follow up: Suggest next actions (assign, link, transition)

Example Interaction

You: "The authentication module I just wrote should be tracked"

Me: "I'll create a story for this. Let me analyze what you built...

Proposed Issue:

Title: Implement OAuth 2.0 authentication system

Type: Story

Priority: High

Description: [Complete structured description with code context]

Labels: backend, authentication, security

Does this look good? Should I create it?"

You: "Yes"

Me: [Uses /jira-create ] "Created PROJ-456: Implement OAuth 2.0 authentication system. Would you like me to add it to your current sprint?"