Spec To Backlog

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:

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

**Source:** https://yoursite.atlassian.net/wiki/spaces/SPECS/pages/123456

**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 or Pages

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

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

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

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

Task Breakdown Examples

This reference provides examples of effective task breakdowns for different types of specifications.

Principles of Good Breakdowns

DO:

• Create tasks that are independently testable
• Group related frontend/backend work logically
• Include explicit testing and documentation tasks
• Use specific, actionable language
• Size tasks for 1-3 days of work typically

DON'T:

• Create overly granular tasks (e.g., "Write one function")
• Make tasks too large (e.g., "Build entire feature")
• Duplicate work across multiple tickets
• Use vague descriptions (e.g., "Do backend stuff")

Example 1: New Feature - User Notifications System

Spec Summary

Add email and in-app notifications for user actions (comments, mentions, updates).

Good Breakdown (8 tasks)

Epic: User Notifications System

1. Design notification data model and database schema

• Define notification types and attributes
• Create database tables and indexes
• Document schema in API docs

2. Implement notification service backend

• Create notification creation/retrieval APIs
• Add notification storage logic
• Implement marking notifications as read

3. Build email notification dispatcher

• Set up email template system
• Implement async email sending queue
• Add email preferences handling

4. Create notification preferences API

• User settings for notification types
• Email vs in-app preferences
• Frequency controls (immediate, digest)

5. Build notification UI components

• Notification bell icon with unread count
• Notification dropdown panel
• Individual notification cards

6. Implement notification settings page

• Frontend for user preferences
• Connect to preferences API
• Add toggle controls for notification types

7. Add notification triggers to existing features

• Hook into comment system
• Hook into mention system
• Hook into update/edit events

8. Write tests and documentation

• Unit tests for notification service
• Integration tests for email delivery
• Update user documentation

Why This Works

• Each task is independently completable
• Clear separation between backend, frontend, and integration
• Testing is explicit
• Tasks are sized appropriately (1-3 days each)

---

Example 2: Bug Fix - Payment Processing Errors

Spec Summary

Users report intermittent payment failures. Investigation shows timeout issues with payment gateway and inadequate error handling.

Good Breakdown (5 tasks)

Epic: Fix Payment Processing Reliability

1. Investigate and document payment failure patterns

• Analyze error logs and failure rates
• Document specific error scenarios
• Create reproduction steps

2. Implement payment gateway timeout handling

• Add configurable timeout settings
• Implement retry logic with exponential backoff
• Add circuit breaker pattern

3. Improve payment error messaging

• Enhance error categorization
• Add user-friendly error messages
• Log detailed errors for debugging

4. Add payment status reconciliation job

• Create background job to verify payment status
• Handle stuck/pending payments
• Send notifications for payment issues

5. Add monitoring and alerting

• Set up payment failure rate alerts
• Add dashboard for payment health metrics
• Document troubleshooting procedures

Why This Works

• Starts with investigation (important for bugs)
• Addresses root cause and symptoms
• Includes monitoring to prevent recurrence
• Each task delivers incremental value

---

Example 3: Infrastructure - Migration to New Database

Spec Summary

Migrate from PostgreSQL 12 to PostgreSQL 15, update queries to use new features, ensure zero downtime.

Good Breakdown (7 tasks)

Epic: PostgreSQL 15 Migration

1. Set up PostgreSQL 15 staging environment

• Provision new database instances
• Configure replication from production
• Verify data consistency

2. Audit and update database queries

• Identify queries using deprecated features
• Update to PostgreSQL 15 syntax
• Optimize queries for new planner

3. Update application connection pooling

• Upgrade database drivers
• Adjust connection pool settings
• Test connection handling under load

4. Create migration runbook

• Document step-by-step migration process
• Define rollback procedures
• List success criteria and validation steps

5. Perform dry-run migration in staging

• Execute full migration process
• Validate data integrity
• Measure downtime duration
• Test rollback procedure

6. Execute production migration

• Follow migration runbook
• Monitor system health during migration
• Validate all services post-migration

7. Post-migration cleanup and monitoring

• Remove old database instances after verification period
• Update monitoring dashboards
• Document lessons learned

Why This Works

• Emphasizes planning and validation
• Includes explicit dry-run
• Risk mitigation with rollback planning
• Clear separation between prep, execution, and cleanup

---

Example 4: API Development - Public REST API

Spec Summary

Create public REST API for third-party integrations. Include authentication, rate limiting, and documentation.

Good Breakdown (9 tasks)

Epic: Public REST API v1

1. Design API specification

• Define endpoints and request/response schemas
• Create OpenAPI/Swagger specification
• Review with stakeholders

2. Implement API authentication system

• Add API key generation and management
• Implement OAuth2 flow
• Create authentication middleware

3. Build rate limiting infrastructure

• Implement token bucket algorithm
• Add per-key rate limit tracking
• Create rate limit headers and responses

4. Implement core API endpoints - Users

• GET /users endpoints
• POST /users endpoints
• PUT/DELETE /users endpoints

5. Implement core API endpoints - Resources

• GET /resources endpoints
• POST /resources endpoints
• PUT/DELETE /resources endpoints

6. Add API versioning support

• Implement version routing
• Add deprecation headers
• Document versioning strategy

7. Create developer portal and documentation

• Set up documentation site
• Add interactive API explorer
• Write getting started guide and examples

8. Build API monitoring and analytics

• Track API usage metrics
• Add error rate monitoring
• Create usage dashboards for customers

9. Write integration tests and SDK examples

• Create comprehensive API test suite
• Write example code in Python/JavaScript
• Document common integration patterns

Why This Works

• Separates authentication and rate limiting (critical infrastructure)
• Groups endpoints by resource type
• Documentation is a first-class task
• Monitoring and developer experience are explicit

---

Example 5: Frontend Redesign - Dashboard Modernization

Spec Summary

Redesign main dashboard with modern UI framework, improve performance, maintain feature parity.

Good Breakdown (8 tasks)

Epic: Dashboard UI Modernization

1. Create new component library foundation

• Set up new UI framework (e.g., React + Tailwind)
• Build reusable component primitives
• Establish design system tokens

2. Build dashboard layout and navigation

• Implement responsive grid layout
• Create new navigation sidebar
• Add breadcrumb and header components

3. Rebuild analytics widgets

• Port existing chart components
• Implement new data visualization library
• Add loading and error states

4. Rebuild data table components

• Create sortable/filterable table
• Add pagination and search
• Implement column customization

5. Implement user settings panel

• Dashboard customization options
• Widget arrangement and visibility
• Preferences persistence

6. Optimize performance and lazy loading

• Implement code splitting
• Add lazy loading for heavy widgets
• Optimize bundle size

7. Add responsive mobile views

• Create mobile-optimized layouts
• Test on various screen sizes
• Implement touch gestures

8. Migration and A/B testing setup

• Create feature flag for new dashboard
• Set up A/B test framework
• Plan gradual rollout strategy

Why This Works

• Foundation first (component library)
• Groups by feature area (analytics, tables)
• Performance and mobile are explicit tasks
• Includes rollout strategy

---

Anti-Patterns to Avoid

Too Granular

❌ Bad:

• "Create User model"
• "Create User controller"
• "Create User view"
• "Write User tests"
• "Update User documentation"

✅ Better:

• "Implement User management feature (model, controller, views, tests)"

Too Vague

❌ Bad:

• "Do backend work"
• "Fix frontend issues"
• "Update database"

✅ Better:

• "Implement user authentication API endpoints"
• "Resolve navigation menu rendering bugs"
• "Add indexes to orders table for query performance"

Missing Testing

❌ Bad:

• Only feature implementation tasks, no testing mentioned

✅ Better:

• Include explicit testing tasks or ensure testing is part of each feature task

No Clear Ownership

❌ Bad:

• Tasks that require both frontend and backend work without clear boundaries

✅ Better:

• Split into "Backend API for X" and "Frontend UI for X" when different people work on each

Epic Description Templates

Effective Epic descriptions provide context, goals, and success criteria. Use these templates based on the type of work.

Template 1: New Feature Epic

## Overview
[1-2 sentence description of what this Epic delivers]

## Source Specification
[Link to Confluence page or design doc]

## Business Value
[Why we're building this - user impact, business goals]

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

## Technical Scope
- **Frontend**: [High-level frontend work]
- **Backend**: [High-level backend work]
- **Infrastructure**: [Any infrastructure needs]
- **Third-party**: [External integrations]

## Out of Scope
- [Explicitly list what's NOT included to prevent scope creep]

## Dependencies
- [List any blocking or related work]

## Launch Plan
- **Target completion**: [Date or sprint]
- **Rollout strategy**: [All at once, gradual, A/B test, etc.]

Example: User Notifications System

## Overview
Add comprehensive notification system supporting email and in-app notifications for user activity (comments, mentions, updates).

## Source Specification
https://company.atlassian.net/wiki/spaces/PRODUCT/pages/123456/Notifications-Spec

## Business Value
Users currently miss important updates, leading to delayed responses and reduced engagement. Notifications will increase daily active usage by an estimated 20% and improve user satisfaction scores.

## Success Criteria
- [ ] Users receive email notifications within 5 minutes of trigger event
- [ ] In-app notifications appear in real-time (< 2 second delay)
- [ ] 80% of users enable at least one notification type
- [ ] Email delivery rate > 95%
- [ ] System handles 10,000 notifications/minute at peak

## Technical Scope
- **Frontend**: Notification bell UI, preferences page, notification cards
- **Backend**: Notification service, email dispatcher, real-time delivery
- **Infrastructure**: Email service integration (SendGrid), websocket server
- **Third-party**: SendGrid for email delivery

## Out of Scope
- Push notifications (mobile) - planned for Q2
- SMS notifications - not in current roadmap
- Notification history beyond 30 days

## Dependencies
- None - self-contained feature

## Launch Plan
- **Target completion**: Sprint 24 (March 15)
- **Rollout strategy**: Gradual rollout, 10% → 50% → 100% over 1 week

---

Template 2: Bug Fix Epic

## Problem Statement
[Clear description of the bug and its impact]

## Source Documentation
[Link to Confluence investigation, incident report, or bug analysis]

## Current Impact
- **Severity**: [Critical/High/Medium/Low]
- **Users affected**: [Percentage or number]
- **Frequency**: [How often it occurs]
- **Business impact**: [Revenue, reputation, etc.]

## Root Cause
[Technical explanation of what's causing the issue]

## Solution Approach
[High-level approach to fixing the issue]

## Success Criteria
- [ ] [Bug no longer reproducible]
- [ ] [Related edge cases handled]
- [ ] [Monitoring in place to detect recurrence]

## Verification Plan
[How we'll confirm the fix works]

Example: Payment Processing Failures

## Problem Statement
Users experiencing intermittent payment failures during checkout, resulting in abandoned transactions and support tickets. Error rate spiked to 8% on Nov 15, up from baseline 0.5%.

## Source Documentation
https://company.atlassian.net/wiki/spaces/ENG/pages/789012/Payment-Failure-Investigation

## Current Impact
- **Severity**: Critical
- **Users affected**: ~800 customers per day
- **Frequency**: 8% of all payment attempts
- **Business impact**: $45K/day in lost revenue, customer trust erosion

## Root Cause
Payment gateway timeouts due to insufficient timeout settings (5s) and no retry logic. During high load, 3rd party payment API occasionally takes 6-8s to respond, causing failures.

## Solution Approach
1. Increase timeout to 15s with exponential backoff retry
2. Implement circuit breaker to prevent cascade failures
3. Add payment reconciliation job to handle stuck transactions
4. Improve error messaging for users

## Success Criteria
- [ ] Payment failure rate below 1%
- [ ] Zero timeout-related failures
- [ ] 100% of stuck payments reconciled within 15 minutes
- [ ] User-facing error messages are clear and actionable

## Verification Plan
- Load testing with simulated gateway delays
- Monitor production metrics for 1 week post-deployment
- Review support tickets for payment-related issues

---

Template 3: Infrastructure/Technical Epic

## Objective
[What infrastructure change or technical improvement we're making]

## Source Documentation
[Link to technical design doc or RFC]

## Current State
[Description of existing system/approach]

## Target State
[Description of desired system/approach after completion]

## Motivation
[Why we need to make this change - performance, cost, maintainability, etc.]

## Success Criteria
- [ ] [Technical metric 1]
- [ ] [Technical metric 2]
- [ ] [Zero downtime or minimal disruption]

## Risk Mitigation
- **Rollback plan**: [How to revert if issues occur]
- **Monitoring**: [What metrics we'll watch]
- **Testing strategy**: [Dry runs, canary deployments, etc.]

## Timeline Constraints
[Any time-sensitive factors like deprecations, costs]

Example: PostgreSQL Migration

## Objective
Migrate primary database from PostgreSQL 12 to PostgreSQL 15 to leverage performance improvements and new features before PostgreSQL 12 EOL.

## Source Documentation
https://company.atlassian.net/wiki/spaces/ENG/pages/345678/PG15-Migration-RFC

## Current State
Running PostgreSQL 12.8 on AWS RDS with 2TB data, 50K queries/minute at peak. Some queries use deprecated features.

## Target State
PostgreSQL 15.2 with optimized queries, improved query planner, and better connection pooling. Estimated 15-20% performance improvement on read-heavy queries.

## Motivation
- PostgreSQL 12 reaches EOL in November 2024
- PG15 query planner improvements will reduce latency on dashboard queries
- New features enable better monitoring and troubleshooting
- Cost savings: ~$800/month from improved efficiency

## Success Criteria
- [ ] Zero data loss during migration
- [ ] < 5 minutes of downtime during cutover
- [ ] All application queries working correctly
- [ ] Query performance same or better than PG12
- [ ] Monitoring confirms system health for 2 weeks

## Risk Mitigation
- **Rollback plan**: Keep PG12 instance available for 2 weeks; can revert in < 15 minutes
- **Monitoring**: Track query latency, error rates, connection pool health
- **Testing strategy**: Full migration dry-run in staging, 24-hour soak test

## Timeline Constraints
Must complete by October 2024 (1 month before PG12 EOL). Testing requires 3 weeks.

---

Template 4: API Development Epic

## Overview
[What API or integration we're building]

## Source Specification
[Link to API design doc or requirements]

## Use Cases
[Primary scenarios this API will enable]

## API Design
- **Authentication**: [Method - API keys, OAuth, etc.]
- **Rate limiting**: [Limits and quotas]
- **Versioning**: [Strategy]
- **Base URL**: [Endpoint structure]

## Endpoints Summary
[High-level list of main endpoint categories]

## Success Criteria
- [ ] [API stability metric]
- [ ] [Performance target]
- [ ] [Documentation completeness]
- [ ] [Developer adoption metric]

## Documentation Deliverables
- [ ] OpenAPI/Swagger spec
- [ ] Getting started guide
- [ ] Code examples (Python, JavaScript)
- [ ] Interactive API explorer

## Timeline
- **Beta release**: [Date]
- **GA release**: [Date]

Example: Public REST API

## Overview
Launch v1 of public REST API enabling third-party developers to integrate with our platform for user management and resource access.

## Source Specification
https://company.atlassian.net/wiki/spaces/API/pages/456789/Public-API-v1-Spec

## Use Cases
- SaaS companies integrating our user management into their products
- Data analytics tools pulling resource data
- Automation platforms connecting workflows
- Mobile app developers building custom clients

## API Design
- **Authentication**: OAuth 2.0 + API keys
- **Rate limiting**: 1,000 requests/hour per API key (higher tiers available)
- **Versioning**: URI-based (/v1/, /v2/)
- **Base URL**: https://api.company.com/v1

## Endpoints Summary
- User management (CRUD operations)
- Resource access (read-only initially)
- Webhooks for event notifications
- Account administration

## Success Criteria
- [ ] 99.9% uptime
- [ ] p95 latency < 200ms
- [ ] Complete OpenAPI documentation
- [ ] 50+ developers signed up for beta
- [ ] Zero security vulnerabilities in initial audit

## Documentation Deliverables
- [x] OpenAPI/Swagger spec
- [ ] Getting started guide
- [ ] Code examples (Python, JavaScript, Ruby)
- [ ] Interactive API explorer (Swagger UI)
- [ ] Authentication tutorial
- [ ] Best practices guide

## Timeline
- **Beta release**: February 15 (invite-only, 10 partners)
- **GA release**: March 30 (public availability)

---

Template 5: Redesign/Modernization Epic

## Overview
[What's being redesigned and why]

## Source Documentation
[Link to design specs, mockups, or requirements]

## Current Pain Points
- [Problem 1 with existing implementation]
- [Problem 2 with existing implementation]
- [Problem 3 with existing implementation]

## New Design Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]

## Success Criteria
- [ ] [User experience metric]
- [ ] [Performance improvement]
- [ ] [Feature parity or improvements]
- [ ] [Accessibility standards met]

## Migration Strategy
[How users transition from old to new]

## Rollout Plan
[Phased rollout, A/B testing, feature flags]

Example: Dashboard Modernization

## Overview
Redesign main analytics dashboard with modern UI framework, improved performance, and better mobile support while maintaining all existing functionality.

## Source Documentation
https://company.atlassian.net/wiki/spaces/DESIGN/pages/567890/Dashboard-Redesign

## Current Pain Points
- Slow initial load time (4-6 seconds)
- Poor mobile experience (not responsive)
- Outdated UI feels "legacy"
- Difficult to customize widget layout
- Accessibility issues (WCAG 2.1 violations)

## New Design Goals
- Modern, clean visual design aligned with brand refresh
- < 2 second initial load time
- Fully responsive (desktop, tablet, mobile)
- Customizable dashboard layouts
- WCAG 2.1 AA compliant
- Improved data visualization clarity

## Success Criteria
- [ ] Initial load time < 2s (50% improvement)
- [ ] Perfect Lighthouse score (90+)
- [ ] Zero WCAG 2.1 AA violations
- [ ] 80% user approval rating in beta test
- [ ] Feature parity with legacy dashboard
- [ ] Mobile usage increases by 30%

## Migration Strategy
- Side-by-side availability during transition
- Users can switch between old/new with toggle
- Preferences automatically migrated
- 30-day sunset period for legacy dashboard

## Rollout Plan
1. Week 1: Internal beta (engineering team)
2. Week 2-3: Customer beta (10% of users via feature flag)
3. Week 4: Expand to 50% of users
4. Week 5: 100% rollout, legacy available via toggle
5. Week 9: Remove legacy dashboard

---

Key Elements in Every Epic

Regardless of template, ensure every Epic includes:

1. Clear objective - Anyone should understand what's being built/fixed 2. Source link - Always link to the Confluence spec or design doc 3. Success criteria - Measurable outcomes that define "done" 4. Scope clarity - What IS and ISN'T included 5. Context - Enough background for someone new to understand why this matters

Common Mistakes to Avoid

❌ Too brief: "Build notifications" - lacks context ❌ Too detailed: Including implementation details that belong in tickets ❌ No success criteria: How do we know when it's done? ❌ Missing source link: Hard to trace back to requirements ❌ Vague scope: Leads to scope creep and confusion

Ticket Writing Guide

Guidelines for creating clear, actionable Jira tickets with effective summaries and descriptions.

Summary Guidelines

The ticket summary should be a clear, concise action statement that immediately tells someone what needs to be done.

Formula

[Action Verb] + [Component/Feature] + [Optional: Context]

Good Examples

✅ "Implement user registration API endpoint" ✅ "Fix pagination bug in search results" ✅ "Add email validation to signup form" ✅ "Optimize database query for dashboard load time" ✅ "Create documentation for payment webhook" ✅ "Design user preferences data schema"

Bad Examples

❌ "Users" - Not actionable ❌ "Do backend work" - Too vague ❌ "Fix bug" - Lacks specificity ❌ "API" - Not a task ❌ "There's an issue with the login page that needs to be addressed" - Too wordy

Action Verbs by Task Type

Development:

• Implement, Build, Create, Add, Develop

Bug Fixes:

• Fix, Resolve, Correct, Debug

Design/Planning:

• Design, Plan, Research, Investigate, Define

Infrastructure:

• Set up, Configure, Deploy, Migrate, Upgrade

Documentation:

• Write, Document, Update, Create

Improvement:

• Optimize, Refactor, Improve, Enhance

Testing:

• Test, Verify, Validate

---

Description Structure

A good ticket description provides context, requirements, and guidance without being overwhelming.

Recommended Template

## Context
[1-2 sentences: Why we're doing this, what problem it solves]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]

## Technical Notes
[Any technical constraints, preferred approaches, or implementation hints]

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

## Resources
- [Link to design mockup if applicable]
- [Link to API documentation]
- [Link to related tickets]

Example 1: Feature Implementation

Summary: Implement user registration API endpoint

Description:

## Context
Users need to create accounts through our REST API. This endpoint will be used by our web app and future mobile apps.

## Requirements
- Accept email, password, and name via POST request
- Validate email format and uniqueness
- Hash password using bcrypt
- Return JWT token for immediate authentication
- Send welcome email asynchronously

## Technical Notes
- Use existing email service for welcome emails
- Follow authentication patterns from login endpoint
- Rate limit: 5 registration attempts per IP per hour

## Acceptance Criteria
- [ ] Endpoint accepts valid registration data and returns 201 with JWT
- [ ] Duplicate email returns 409 error
- [ ] Invalid email format returns 400 error
- [ ] Password must be 8+ characters
- [ ] Welcome email sent within 1 minute
- [ ] Unit tests cover happy path and error cases

## Resources
- API Spec: https://company.atlassian.net/wiki/API-Design
- Related: AUTH-123 (Login endpoint)

Example 2: Bug Fix

Summary: Fix pagination bug in search results

Description:

## Context
Users report that clicking "Next Page" in search results sometimes shows duplicate items from the previous page. This happens intermittently when search results are sorted by date.

## Problem
The pagination offset calculation doesn't account for items with identical timestamps, causing cursor position drift when using timestamp-based pagination.

## Requirements
- Ensure each search result appears exactly once
- Maintain current sort order (date descending)
- Fix applies to all search endpoints

## Technical Notes
- Current implementation uses timestamp as cursor: `?cursor=2024-01-15T10:30:00Z`
- Suggested fix: Composite cursor using timestamp + ID
- Consider adding unique index on (timestamp, id) for better query performance

## Acceptance Criteria
- [ ] No duplicate items appear across paginated results
- [ ] Pagination works correctly with items having identical timestamps
- [ ] All existing search API tests still pass
- [ ] Added test case reproducing the original bug
- [ ] Performance impact < 5ms per query

## Resources
- Bug Report: https://company.atlassian.net/wiki/BUG-456
- Related: SEARCH-789 (Original search implementation)

Example 3: Infrastructure Task

Summary: Set up PostgreSQL 15 staging environment

Description:

## Context
First step in database migration from PG12 to PG15. Need staging environment to validate migration process and test query compatibility.

## Requirements
- Provision PG15 instance matching production specs
- Set up replication from production to staging
- Configure backup retention (7 days)
- Enable query logging for testing

## Technical Notes
- Use AWS RDS PostgreSQL 15.2
- Instance type: db.r6g.2xlarge (same as prod)
- Enable logical replication for zero-downtime testing
- VPC: staging-vpc-us-east-1

## Acceptance Criteria
- [ ] PG15 instance running and accessible from staging apps
- [ ] Replication lag < 30 seconds from production
- [ ] Can connect using standard credentials
- [ ] Query logs enabled and viewable
- [ ] Monitoring dashboards created
- [ ] Backup configured and tested (restore test)

## Resources
- Migration RFC: https://company.atlassian.net/wiki/PG15-Migration
- Infrastructure docs: https://wiki/Database-Setup
- Parent Epic: INFRA-100

Example 4: Frontend Task

Summary: Create notification bell UI component

Description:

## Context
Part of notification system. Need UI component showing unread notification count and opening notification panel.

## Requirements
- Bell icon in top navigation bar
- Display unread count badge (e.g., "5")
- Click opens notification dropdown panel
- Real-time updates via WebSocket
- Badge turns red for urgent notifications

## Technical Notes
- Use existing Icon component library
- WebSocket events: 'notification:new', 'notification:read'
- State management: Context API or Zustand
- Position: Right side of nav, left of user avatar

## Acceptance Criteria
- [ ] Bell icon displays in navigation bar
- [ ] Unread count badge shows accurate count
- [ ] Badge updates in real-time when new notification arrives
- [ ] Click opens/closes notification panel
- [ ] No badge shown when count is 0
- [ ] Component is accessible (keyboard navigation, screen reader)
- [ ] Responsive design (mobile, tablet, desktop)

## Resources
- Design mockup: [Figma link]
- WebSocket docs: https://wiki/Notifications-API
- Related: NOTIF-123 (Notification panel component)

---

Descriptions by Task Type

Backend Development

Focus on:

• API contract (request/response format)
• Data validation rules
• Error handling requirements
• Performance expectations
• Security considerations

Frontend Development

Focus on:

• Visual design reference
• User interactions
• State management approach
• Responsive behavior
• Accessibility requirements

Bug Fixes

Focus on:

• Reproduction steps
• Expected vs actual behavior
• Root cause (if known)
• Affected users/scenarios
• Verification approach

Testing

Focus on:

• What needs testing (features, edge cases)
• Test coverage targets
• Types of tests (unit, integration, e2e)
• Performance benchmarks
• Test data requirements

Documentation

Focus on:

• Target audience
• Required sections/topics
• Examples to include
• Existing docs to update
• Review/approval process

---

Acceptance Criteria Best Practices

Acceptance criteria should be:

1. Testable - Can verify by testing or observation 2. Specific - No ambiguity about what "done" means 3. Complete - Covers all requirements in description 4. User-focused - When possible, frame from user perspective

Good Acceptance Criteria

✅ "User can submit form and receive confirmation email within 30 seconds" ✅ "API returns 400 error when email field is empty" ✅ "Dashboard loads in under 2 seconds on 3G connection" ✅ "All text meets WCAG 2.1 AA contrast ratios"

Bad Acceptance Criteria

❌ "Feature works well" - Not specific ❌ "Code is clean" - Subjective, not testable ❌ "Fast performance" - Not measurable ❌ "No bugs" - Too broad

---

Technical Notes Guidelines

Use "Technical Notes" section for:

• Architectural decisions: "Use Redis for session caching"
• Implementation hints: "Follow pattern from UserService class"
• Performance constraints: "Query must complete in < 100ms"
• Security requirements: "Use parameterized queries to prevent SQL injection"
• Dependencies: "Requires AUTH-456 to be deployed first"
• Gotchas: "Watch out for timezone handling in date comparisons"

Keep it concise - detailed technical specs belong in Confluence or code comments.

---

Common Mistakes to Avoid

1. Information Overload

❌ Pages of requirements copied from spec doc ✅ Summary with link to full spec

2. Assuming Context

❌ "Fix the bug we discussed" ✅ Clear description of the bug with reproduction steps

3. Implementation as Requirement

❌ "Use React hooks for state management" ✅ "Component updates in real-time" (let developer choose approach unless there's a specific reason)

4. Vague Acceptance Criteria

❌ "Everything works correctly" ✅ Specific, testable outcomes

5. Missing Links

❌ No reference to designs, specs, or related work ✅ Links to all relevant documentation

---

Length Guidelines

Summary:

• Target: 3-8 words
• Max: 12 words

Description:

• Target: 100-300 words
• Min: Include at minimum context and acceptance criteria
• Max: 500 words (link to docs for more detail)

Acceptance Criteria:

• Target: 3-7 items
• Each item: 1 sentence

Remember: Ticket descriptions are not documentation. They're instructions for completing a specific task.