| name | spec-to-backlog |
| description | Transform specification documents into structured Jira backlogs using jira-cli. When an agent needs to: (1) Create Jira tickets from a spec or requirements document, (2) Break down a feature spec into implementation tasks, (3) Create an epic with child tickets from a design doc, or (4) Convert requirements into a Jira backlog. |
Spec to Backlog
Transform specification documents into structured Jira backlogs using jira-cli. This skill reads requirement documents, intelligently breaks them down into logical implementation tasks, creates an Epic first, then generates individual Jira tickets linked to that Epic.
Use this skill when: Users have a spec, requirements doc, or design document that needs to become a Jira backlog.
All commands use --plain for clean output and --no-input to skip interactive prompts.
Workflow
CRITICAL: Always follow this exact sequence:
- Get Specification → Obtain the spec content
- Confirm Project and Epic Details → Identify target Jira project
- Analyze Specification → Break down into logical tasks
- Present Breakdown → Show user the planned Epic and tickets
- Create Epic FIRST → Establish parent Epic and capture its key
- Create Child Tickets → Generate tickets linked to the Epic
- Provide Summary → Present all created items with links
Step 1: Get Specification
Ask the user to provide the spec. This can be:
- Pasted text directly in the conversation
- A file path to read
- A URL to fetch
Step 2: Confirm Project and Epic Details
Ask: "Which Jira project should I create these tickets in? (e.g., MGMT, ENG)"
If the user is unsure:
jira project list --plain
Step 3: Analyze Specification
Read the spec and decompose it into:
Epic-Level Goal
What is the overall objective? This becomes your Epic.
Implementation Tasks
Break the work into logical, independently implementable tasks.
Breakdown principles:
- Size: 3-10 tasks per spec typically
- Clarity: Each task should be specific and actionable
- Independence: Tasks can be worked on separately when possible
- Completeness: Include backend, frontend, testing, documentation, and infrastructure tasks when the spec touches those areas
Choose appropriate issue types based on content:
- Bug — Fixing existing problems ("fix", "resolve", "broken")
- Story — New user-facing features ("feature", "user can", "add ability to")
- Task — Technical work without direct user impact ("implement", "setup", "configure", "refactor")
Use action verbs: Implement, Create, Build, Add, Design, Integrate, Update, Fix, Optimize, Configure, Deploy, Test, Document
Step 4: Present Breakdown to User
Before creating anything, show the user your planned breakdown:
I've analyzed the spec and here's the backlog I'll create:
**Epic:** [Epic Summary]
[Brief description of epic scope]
**Implementation Tickets (7):**
1. [Story] Create user registration flow
2. [Task] Design authentication database schema
3. [Story] Build login form UI components
4. [Bug] Fix existing session timeout handling
5. [Task] Configure CI/CD pipeline for auth service
6. [Story] Implement password reset API
7. [Task] Write integration tests for auth flow
Shall I create these tickets in [PROJECT]?
Wait for user confirmation before proceeding.
Step 5: Create Epic FIRST
The Epic must be created before any child tickets.
jira epic create \
-s "Epic Summary" \
-b $'## Overview\nBrief summary of what this epic delivers\n\n## Objectives\n- Key objective 1\n- Key objective 2\n\n## Scope\nWhat is included and what is not\n\n## Success Criteria\n- Measurable criterion 1\n- Measurable criterion 2' \
-l OSAC --no-input
Capture the Epic key from the output (e.g., "MGMT-123"). You'll need it for every child ticket.
Confirm to user: "Created Epic: MGMT-123 - Epic Summary"
Step 6: Create Child Tickets
Create each implementation task as a child ticket linked to the Epic.
For Each Task
jira issue create -t<IssueType> \
-s "Task summary with action verb" \
-b $'## Context\nBrief context from the spec\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Technical Details\n- Technologies involved\n- Dependencies\n\n## Acceptance Criteria\n- [ ] Testable criterion 1\n- [ ] Testable criterion 2' \
-P <EPIC-KEY> -l OSAC --no-input
Where <IssueType> is one of: Task, Story, Bug
Task Summary Format
- "Implement user registration API endpoint"
- "Design authentication database schema"
- "Build login form UI components"
- NOT "Do backend work" (too vague)
- NOT "Frontend" (not actionable)
Acceptance Criteria Best Practices
Make them testable and specific:
- "API returns 201 status on successful user creation"
- "Password must be at least 8 characters and hashed with bcrypt"
- NOT "User can log in" (too vague)
- NOT "It works" (not testable)
Step 7: Provide Summary
After all tickets are created:
Backlog created successfully!
**Epic:** MGMT-123 - User Authentication System
https://redhat.atlassian.net/browse/MGMT-123
**Implementation Tickets (7):**
1. MGMT-124 - Design authentication database schema
https://redhat.atlassian.net/browse/MGMT-124
2. MGMT-125 - Implement user registration API endpoint
https://redhat.atlassian.net/browse/MGMT-125
3. MGMT-126 - Build login form UI components
https://redhat.atlassian.net/browse/MGMT-126
Next Steps:
- Review tickets in Jira for accuracy and completeness
- Assign tickets to team members
- Estimate story points if your team uses them
- Schedule work for the upcoming sprint
Edge Cases
Existing Epic
If user wants to add tickets to an existing Epic:
- Skip Epic creation (Step 5)
- Ask for the existing Epic key
- Proceed with Step 6 using the provided Epic key
Large Specifications (15+ tickets)
- Present the full breakdown
- Ask: "This spec would create 18 tickets. Should I create all of them, or would you like to adjust the scope?"
- Offer to create a subset first
Ambiguous Specifications
If the spec lacks detail:
- Create fewer, broader tickets
- Note in descriptions: "Detailed requirements need to be defined during refinement"
- Ask: "The spec is light on implementation details. Should I create high-level tickets that can be refined later?"
Tips for High-Quality Breakdowns
- Be Specific — "Create login form UI with email/password inputs and validation" not "Do frontend work"
- Include Technical Context — Mention technologies, components, integration points
- Logical Grouping — Related work stays in the same ticket
- Avoid Duplication — Don't create redundant tickets
- Note Dependencies — Use "Depends on" or "Blocks" in descriptions
- Include Testing — Either as part of feature tasks or as separate testing tasks
When NOT to Use This Skill
Don't use for:
- Individual task creation (use jira-task-management)
- Meeting action items (use capture-tasks-from-meeting-notes)
- Bug triaging (use triage-issue)
Use only when: A spec or requirements document needs to become a structured Jira backlog.
