| name | Structured Issue Creation |
| description | Create well-structured Jira issues from code changes, conversations, or requirements. Use when creating issues, bugs, stories, tasks, or when the user wants to track work in Jira. Analyzes context to generate clear titles, descriptions, and appropriate fields. |
| allowed-tools | Read, Grep, Bash |
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 charactersAdd dark mode toggle to settingsRefactor 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, databasemobile, web, desktop
Technical Labels
performance, security, accessibilitytechnical-debt, refactoring
Process Labels
needs-design, needs-review, blockedgood-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:
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?"
