Spec to Backlog

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: Fetch Confluence Page

When triggered, obtain the Confluence page content:

If user provides a Confluence URL:

Extract the cloud ID and page ID from the URL pattern:

• Standard format: https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]
• The cloud ID can be extracted from [site].atlassian.net or by calling getAccessibleAtlassianResources
• The page ID is the numeric value in the URL path

If user provides only a page title or description:

Use the search tool to find the page:

search(
  cloudId="...",
  query="type=page AND title~'[search terms]'"
)

If multiple pages match, ask the user to clarify which one to use.

Fetch the page:

Call getConfluencePage with the cloudId and pageId:

getConfluencePage(
  cloudId="...",
  pageId="123456",
  contentFormat="markdown"
)

This returns the page content in Markdown format, which you'll analyze in 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 Confluence page 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]

## Source
Confluence Spec: [Link to Confluence page]

## 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.

Example response:

{
  "key": "PROJ-123",
  "id": "10001",
  "self": "https://yoursite.atlassian.net/rest/api/3/issue/10001"
}

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"
• ❌ "Do backend work" (too vague)
• ❌ "Frontend" (not actionable)

Task Description Structure:

## Context
[Brief context for this task from the Confluence 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
- Confluence Spec: [Link to relevant section if possible]
- 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"
• ❌ "User can log in" (too vague)
• ❌ "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