/spec-to-backlog

name: spec-to-backlog
description: "Automatically convert Confluence specification documents into structured Jira backlogs with Epics and implementation tickets. When an agent needs to: (1) Create Jira tickets from a Confluence page, (2) Generate a backlog from a specification, (3) Break down a spec into implementation tasks, or (4) Convert requirements into Jira issues. Handles reading Confluence pages, analyzing specifications, creating Epics with proper structure, and generating detailed implementation tickets linked to the Epic."

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 `searchConfluence` with a CQL query to find the page by title:

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

> **Do not put CQL into `search`.** The `search` tool is Rovo semantic search and takes natural > language, not query syntax — passing CQL to it will miss the page. Use `search` only for > natural-language discovery (`query="one-click checkout spec"`), and `searchConfluence` when you > want a title or type filter.

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

Fetch the page:

Call `getConfluenceContent` with the cloudId and content ID:

getConfluenceContent(
  cloudId="...",
  content_id="123456",
  content_format="markdown",
  detail="full"
)

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 `listJiraProjects` to show available projects. It is not a primary tool, so run it through `execute` (see [Calling non-primary tools](#calling-non-primary-tools)):

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjects",
  cloudId="...",
  inputs={"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 `listJiraProjectIssueTypesMetadata` to understand what issue types are available. This is also not a primary tool:

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjectIssueTypesMetadata",
  cloudId="...",
  inputs={"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 Per