spec-to-backlog

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

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.

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.

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

Call listJiraProjects to show available projects. It is not a primary tool, so run it through execute (see 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)."

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")

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"

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

Call createJiraIssue with:

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

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"

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",
  issueType="[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)

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)

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)

Track each created ticket key for the summary.

If user references multiple Confluence pages:

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

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

If ticket creation fails due to required fields:

1. Use getJiraIssueTypeMetaWithFields to identify what fields are required. It is not a primary tool, so run it through execute:

   Copy

   executeRead(   # or execute(...) if your client exposes a single execute tool
     name="getJiraIssueTypeMetaWithFields",
     cloudId="...",
     inputs={"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. Pass native parameters directly — priority is a top-level string, not an additional_fields entry. Reserve additional_fields for custom fields:

   Copy

   priority="High",
   additional_fields={"customfield_10001": {"value": "Production"}}

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

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

If the Confluence page 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?"

If createJiraIssue fails:

1. Check the error message for specific issues (permissions, required fields, invalid values)
2. Use executeRead(name="listJiraProjectIssueTypesMetadata", ...) 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."

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

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

• 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

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

• 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")

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

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

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

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

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