spec-to-backlog

Spec to Backlog

Overview

Transform specifications into structured Jira backlogs automatically. This skill reads requirement documents from any source — markdown files, free text, or conversation context — intelligently breaks them down into logical implementation tasks, creates an Epic first to organize the work, then generates individual Jira tickets linked to that Epic - eliminating tedious manual copy-pasting.

Core Workflow

CRITICAL: Always follow this exact sequence:

1. Obtain Spec Content -> Get the specification content from context, file, or user
2. Ask for Project Key -> Identify target Jira project
3. Analyze Specification -> Break down into logical tasks (internally, don't create yet)
4. Present Breakdown -> Show user the planned Epic and tickets
5. Create Epic FIRST -> Establish parent Epic and capture its key
6. Create Child Tickets -> Generate tickets linked to the Epic
7. Provide Summary -> Present all created items with links

Why Epic must be created first: Child tickets need the Epic key to link properly during creation. Creating tickets first will result in orphaned tickets.

---

Step 1: Obtain Specification Content

Determine where the specification content comes from before proceeding.

If spec content is already in the conversation

The user may have pasted markdown, free text, a requirements doc, or described the feature in the conversation. If there is enough content to analyze, proceed directly to Step 3.

If the user referenced a file path

Read the file directly if it is accessible. For a local markdown file, read its contents and proceed to Step 3.

If spec content is missing or unclear

Ask the user to provide the specification:

"Please share the specification content — you can paste markdown, free text, or describe the feature you want to break down into Jira tickets."

Wait for the user's response, then proceed to Step 3.

---

Step 2: Ask for Project Key

Before analyzing the spec, determine the target Jira project:

Ask the user

"Which Jira project should I create these tickets in? Please provide the project key (e.g., PROJ, ENG, PRODUCT)."

If user is unsure

Call getVisibleJiraProjects to show available projects:

getVisibleJiraProjects(
  cloudId="...",
  action="create"
)

Present the list: "I found these projects you can create issues in: PROJ (Project Alpha), ENG (Engineering), PRODUCT (Product Team)."

Once you have the project key

Call getJiraProjectIssueTypesMetadata to understand what issue types are available:

getJiraProjectIssueTypesMetadata(
  cloudId="...",
  projectIdOrKey="PROJ"
)

Identify available issue types:

• Which issue type is "Epic" (or similar parent type like "Initiative")
• What child issue types are available: "Story", "Task", "Bug", "Sub-task", etc.

Select appropriate issue types for child tickets:

The skill should intelligently choose issue types based on the specification content:

Use "Bug" when the spec describes:

• Fixing existing problems or defects
• Resolving errors or incorrect behavior
• Addressing performance issues
• Correcting data inconsistencies
• Keywords: "fix", "resolve", "bug", "issue", "problem", "error", "broken"

Use "Story" when the spec describes:

• New user-facing features or functionality
• User experience improvements
• Customer-requested capabilities
• Product enhancements
• Keywords: "feature", "user can", "add ability to", "new", "enable users"

Use "Task" when the spec describes:

• Technical work without direct user impact
• Infrastructure or DevOps work
• Refactoring or optimization
• Documentation or tooling
• Configuration or setup
• Keywords: "implement", "setup", "configure", "optimize", "refactor", "infrastructure"

Fallback logic:

1. If "Story" is available and content suggests new features -> use "Story"
2. If "Bug" is available and content suggests fixes -> use "Bug"
3. If "Task" is available -> use "Task" for technical work
4. If none of the above are available -> use the first available non-Epic, non-Subtask issue type

Store the selected issue types for use in Step 6:

• Epic issue type name (e.g., "Epic")
• Default child issue type (e.g., "Story" or "Task")
• Bug issue type name if available (e.g., "Bug")

---

Step 3: Analyze Specification

Read the specification content and internally decompose it into:

Epic-Level Goal

What is the overall objective or feature being implemented? This becomes your Epic.

Example Epic summaries:

• "User Authentication System"
• "Payment Gateway Integration"
• "Dashboard Performance Optimization"
• "Mobile App Notifications Feature"

Implementation Tasks

Break the work into logical, independently implementable tasks.

Breakdown principles:

• Size: 3-10 tasks per spec typically (avoid over-granularity)
• Clarity: Each task should be specific and actionable
• Independence: Tasks can be worked on separately when possible
• Completeness: Include backend, frontend, testing, documentation, infrastructure as needed
• Grouping: Related functionality stays in the same ticket

Consider these dimensions:

• Technical layers: Backend API, Frontend UI, Database, Infrastructure
• Work types: Implementation, Testing, Documentation, Deployment
• Features: Break complex features into sub-features
• Dependencies: Identify prerequisite work

Common task patterns:

• "Design [component] database schema"
• "Implement [feature] API endpoints"
• "Build [component] UI components"
• "Add [integration] to existing [system]"
• "Write tests for [feature]"
• "Update documentation for [feature]"

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:

Format:

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] [Task 1 Summary]
2. [Task] [Task 2 Summary]
3. [Story] [Task 3 Summary]
4. [Bug] [Task 4 Summary]
5. [Task] [Task 5 Summary]
6. [Story] [Task 6 Summary]
7. [Task] [Task 7 Summary]

Shall I create these tickets in [PROJECT KEY]?

The issue type labels show what type each ticket will be created as:

• [Story] - New user-facing feature
• [Task] - Technical implementation work
• [Bug] - Fix or resolve an issue

Wait for user confirmation before proceeding. This allows them to:

• Request changes to the breakdown
• Confirm the scope is correct
• Adjust the number or focus of tickets

If user requests changes, adjust the breakdown and re-present.

---

Step 5: Create Epic FIRST

CRITICAL: The Epic must be created before any child tickets.

Create the Epic

Call createJiraIssue with:

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueTypeName="Epic",
  summary="[Epic Summary from Step 3]",
  description="[Epic Description - see below]"
)

Epic Description Structure

## Overview
[1-2 sentence summary of what this epic delivers]

## Objectives
- [Key objective 1]
- [Key objective 2]
- [Key objective 3]

## Scope
[Brief description of what's included and what's not]

## Success Criteria
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Measurable criterion 3]

## Technical Notes
[Any important technical context from the spec]

Capture the Epic Key

The response will include the Epic's key (e.g., "PROJ-123"). Save this key - you'll need it for every child ticket.

Confirm Epic creation to user: "Created Epic: PROJ-123 - User Authentication System"

---

Step 6: Create Child Tickets

Now create each implementation task as a child ticket linked to the Epic.

For each task

Determine the appropriate issue type for this specific task:

• If the task involves fixing/resolving an issue -> use "Bug" (if available)
• If the task involves new user-facing features -> use "Story" (if available)
• If the task involves technical/infrastructure work -> use "Task" (if available)
• Otherwise -> use the default child issue type from Step 2

Call createJiraIssue with:

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueTypeName="[Story/Task/Bug based on task content]",
  summary="[Task Summary]",
  description="[Task Description - see below]",
  parent="PROJ-123"  # The Epic key from Step 5
)

Example issue type selection:

• "Fix authentication timeout bug" -> Use "Bug"
• "Build user dashboard UI" -> Use "Story"
• "Configure CI/CD pipeline" -> Use "Task"
• "Implement password reset API" -> Use "Story" (new user feature)

Task Summary Format

Use action verbs and be specific:

• "Implement user registration API endpoint"
• "Design authentication database schema"
• "Build login form UI components"
• NOT "Do backend work" (too vague)
• NOT "Frontend" (not actionable)

Task Description Structure

## Context
[Brief context for this task from the spec]

## Requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Technical Details
[Specific technical information relevant to this task]
- Technologies: [e.g., Node.js, React, PostgreSQL]
- Components: [e.g., API routes, database tables, UI components]
- Dependencies: [e.g., requires PROJ-124 to be completed first]

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]

## Related
- Epic: PROJ-123

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"
• "Login form validates email format before submission"
• NOT "User can log in" (too vague)
• NOT "It works correctly" (not testable)

Create all tickets sequentially

Track each created ticket key for the summary.

---

Step 7: Provide Summary

After all tickets are created, present a comprehensive summary:

Backlog created successfully!

**Epic:** PROJ-123 - User Authentication System
https://yoursite.atlassian.net/browse/PROJ-123

**Implementation Tickets (7):**

1. PROJ-124 - Design authentication database schema
   https://yoursite.atlassian.net/browse/PROJ-124

2. PROJ-125 - Implement user registration API endpoint
   https://yoursite.atlassian.net/browse/PROJ-125

3. PROJ-126 - Implement user login API endpoint
   https://yoursite.atlassian.net/browse/PROJ-126

4. PROJ-127 - Build login form UI components
   https://yoursite.atlassian.net/browse/PROJ-127

5. PROJ-128 - Build registration form UI components
   https://yoursite.atlassian.net/browse/PROJ-128

6. PROJ-129 - Add authentication integration to existing features
   https://yoursite.atlassian.net/browse/PROJ-129

7. PROJ-130 - Write authentication tests and documentation
   https://yoursite.atlassian.net/browse/PROJ-130

**Next Steps:**
- Review tickets in Jira for accuracy and completeness
- Assign tickets to team members
- Estimate story points if your team uses them
- Add any additional labels or custom field values
- Schedule work for the upcoming sprint

---

Edge Cases & Troubleshooting

Multiple Specs

If user references multiple documents:

• Process each separately, or ask which to prioritize
• Consider creating separate Epics for distinct features
• "I see you've provided content for 3 different features. Should I create separate Epics for each, or would you like me to focus on one first?"

Existing Epic

If user wants to add tickets to an existing Epic:

• Skip Epic creation (Step 5)
• Ask for the existing Epic key: "What's the Epic key you'd like to add tickets to? (e.g., PROJ-100)"
• Proceed with Step 6 using the provided Epic key

Custom Required Fields

If ticket creation fails due to required fields:

1. Use getJiraIssueTypeMetaWithFields to identify what fields are required:

   getJiraIssueTypeMetaWithFields(
     cloudId="...",
     projectIdOrKey="PROJ",
     issueTypeId="10001"
   )
   

2. Ask user for values: "This project requires a 'Priority' field. What priority should I use? (e.g., High, Medium, Low)"

3. Include in additional_fields when creating:

   additional_fields={
     "priority": {"name": "High"}
   }
   

Large Specifications

For specs that would generate 15+ tickets:

• Present the full breakdown to user
• 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: "I can create the first 10 tickets now and wait for your feedback before creating the rest."

Subtasks vs Tasks

Some projects use "Subtask" issue types:

• If metadata shows "Subtask" is available, you can use it for more granular work
• Subtasks link to parent tasks (not Epics directly)
• Structure: Epic -> Task -> Subtasks

Ambiguous Specifications

If the specification lacks detail:

• Create fewer, broader tickets
• Note in ticket descriptions: "Detailed requirements need to be defined during refinement"
• Ask user: "The spec is light on implementation details. Should I create high-level tickets that can be refined later?"

Failed API Calls

If createJiraIssue fails:

1. Check the error message for specific issues (permissions, required fields, invalid values)
2. Use getJiraProjectIssueTypesMetadata to verify issue type availability
3. Inform user: "I encountered an error creating tickets: [error message]. This might be due to project permissions or required fields."

---

Tips for High-Quality Breakdowns

Be Specific

• NOT "Do frontend work"
• "Create login form UI with email/password inputs and validation"

Include Technical Context

• Mention specific technologies when clear from spec
• Reference components, services, or modules
• Note integration points

Logical Grouping

• Related work stays in the same ticket
• Don't split artificially: "Build user profile page" includes both UI and API integration
• Do split when different specialties: Separate backend API task from frontend UI task if worked on by different people

Avoid Duplication

• Don't create redundant tickets for the same functionality
• If multiple features need the same infrastructure, create one infrastructure ticket they all depend on

Explicit Testing

• Include testing as part of feature tasks ("Implement X with unit tests")
• OR create separate testing tasks for complex features ("Write integration tests for authentication flow")

Documentation Tasks

• For user-facing features: Include "Update user documentation" or "Create help articles"
• For developer tools: Include "Update API documentation" or "Write integration guide"

Dependencies

• Note prerequisites in ticket descriptions
• Use "Depends on" or "Blocks" relationships in Jira if available
• Sequence tickets logically (infrastructure -> implementation -> testing)

---

Examples of Good Breakdowns

Example 1: New Feature - Search Functionality

Epic: Product Search and Filtering

Tickets:

1. [Task] Design search index schema and data structure
2. [Task] Implement backend search API with Elasticsearch
3. [Story] Build search input and results UI components
4. [Story] Add advanced filtering (price, category, ratings)
5. [Story] Implement search suggestions and autocomplete
6. [Task] Optimize search performance and add caching
7. [Task] Write search integration tests and documentation

Example 2: Bug Fix - Performance Issue

Epic: Resolve Dashboard Load Time Issues

Tickets:

1. [Task] Profile and identify performance bottlenecks
2. [Bug] Optimize database queries with indexes and caching
3. [Bug] Implement lazy loading for dashboard widgets
4. [Bug] Add pagination to large data tables
5. [Task] Set up performance monitoring and alerts

Example 3: Infrastructure - CI/CD Pipeline

Epic: Automated Deployment Pipeline

Tickets:

1. [Task] Set up GitHub Actions workflow configuration
2. [Task] Implement automated testing in CI pipeline
3. [Task] Configure staging environment deployment
4. [Task] Implement blue-green production deployment
5. [Task] Add deployment rollback mechanism
6. [Task] Create deployment runbook and documentation

---

Resources

For detailed templates and examples, see the references/ directory:

• epic-templates.md - Epic description templates
• breakdown-examples.md - Task breakdown examples
• ticket-writing-guide.md - Guidelines for writing clear tickets