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
1. Go to login page
2. Enter email with + character
3. 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
- [x] Google OAuth integration working
- [x] GitHub OAuth integration working
- [x] Error handling for failed OAuth
- [x] Tests added and passing
- [ ] Documentation updated
- [ ] Security review completed

## 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:
1. Epic: Payment Integration
2. Story: Stripe API integration
3. Story: Payment form UI
4. Story: Transaction history
5. 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?"