spec-to-backlog

What this skill does

# Spec to Backlog

## Overview

Transform Confluence specification documents into structured Jira backlogs automatically. This skill reads requirement documents from Confluence, 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. **Fetch Confluence Page** → Get the specification content
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: 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:

```markdown
## 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:**
```json
{
  "key": "PROJ-123",
  "id": "10001",
  "self": "https://yoursite.atlassian.net/rest/api/3/issue/10001"
}
```

**Confirm Epic creation to user:**
"✅ Created