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"

Superpowers Integration

This skill complements the superpowers workflow skills. Use superpowers skills first for process guidance, then this skill for Jira execution:

Situation	Use Superpowers First	Then Use This Skill
New feature request	brainstorming → design the feature	Create Story with requirements
Complex bug	systematic-debugging → find root cause	Create Bug with findings
Multi-step work	writing-plans → break down tasks	Create Epic + linked Stories
After completing work	finishing-a-development-branch → verify	Update issue status

Key principle: Superpowers handles the how (methodology), this plugin handles the where (Jira tracking).

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

Note: Priority names vary by Jira instance. Common values include: Blocker, Critical, Major, Minor, Trivial (classic) or Highest, High, Medium, Low, Lowest. Check an existing issue in your project to confirm.

🔴 Blocker / Highest

• Production outages
• Security vulnerabilities
• Data loss scenarios
• Blocking other work

🟠 Critical / High

• Significant bugs affecting many users
• Important features with deadlines
• Performance issues

🟡 Major / Medium

• Minor bugs
• Feature enhancements
• Technical debt

🟢 Minor / Low

• 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:

1. Analyze the change:

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

2. Determine issue type:

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

3. Extract details:

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

4. 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:

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

2. Ask clarifying questions if needed:

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

3. Structure the information: Use appropriate template

4. 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:

1. Gather context: Understand what you want to track
2. Determine type: Bug, Story, Task, or Epic?
3. Structure content: Use appropriate template
4. Add metadata: Priority, labels, relationships
5. Show preview: Let you review before creating
6. Create issue: Use /jira-create command
7. 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?"