JIRA Engineering Guide

How teams manage work, sprints, and delivery in Jira

This guide defines how engineering teams use Jira to plan, track, and deliver work.

The goal is not process for the sake of process. The goal is to ensure:

• Work is visible

• Teams stay focused

• Blockers surface quickly

• Engineering metrics remain accurate

Jira should reflect how work actually happens, not create unnecessary bureaucracy.

---

1. Jira Project Setup

Use Company-Managed Projects

All engineering projects should use Company-Managed Projects.

Benefits:

• shared workflows

• consistent metrics

• easier administration

• cross-team reporting

---

Use a Master Project Template

Create one project as the base template:

TEMPLATE: Standard Software Project

When creating new projects:

1. Select Company-Managed

2. Choose Create with shared configuration

3. Copy configuration from the template

This ensures all teams start with the same:

• workflows

• issue types

• fields

• board configuration

---

Avoid Too Many Projects

Projects should represent products or services, not teams.

Bad example:

Frontend Team
Backend Team
Infra Team

Better structure:

Payments
Platform
Analytics
Mobile

Use Components inside projects to represent system areas.

---

2. Issue Types & Work Hierarchy

Use consistent issue types across projects.

Issue Type	Purpose
Epic	Large initiative spanning multiple sprints
Story	User-facing feature or requirement
Task	Technical work not tied to a user story
Bug	Defect discovered during development or testing
Incident	Production issue affecting customers
Sub-task	Small step within a story shared across contributors

---

When to Use Epics

If work cannot be completed within one sprint, it likely belongs in an Epic.

Example:

Epic

Launch Payment Retry System

Stories

Retry payment API
Retry UI flow
Payment retry logging

---

3. Components vs Labels

Both help categorize work but serve different purposes.

Components

Used for stable system areas

Example:

Frontend
Backend
Infrastructure
API
Mobile

Limit components to 5–7 major areas.

---

Labels

Used for temporary tags or themes

Example:

tech-debt
security
migration
experiment
performance

Avoid using labels for system areas.

---

4. Workflow Design

Workflows should remain simple and consistent.

Recommended workflow:

Backlog → To Do → In Progress → In Testing → Ready For Release → Done

Why simplicity matters:

Teams often forget to update complex workflows, which breaks delivery metrics like cycle time.

If additional QA steps exist, they can happen within Review.

---

Jira Status Categories

Jira groups statuses into three categories:

Category	Meaning
Blue	To Do
Yellow	In Progress
Green	Done

Ensure statuses map correctly.

Example:

In Testing → In Progress category
Ready For Release → In Progress category

Otherwise, Jira may treat work as completed too early.

---

5. Handling Blockers

Avoid creating a separate Blocked status in most cases.

Instead use Jira Flags.

How to flag:

Right click issue → Add Flag

Example scenario:

Waiting for API documentation
Waiting for design approval

Ticket remains:

In Progress (Flagged)

Create a Blocked status only if your organization needs blocked-time metrics.

---

6. Board Setup & Work-in-Progress Limits

Boards should mirror the workflow:

Backlog
To Do
In Progress
In Review
Done

---

WIP Limits

Avoid starting too many tasks simultaneously.

Recommended rule:

WIP Limit = Team Size × 1.5

Example:

3 developers → WIP limit of 4–5.

This encourages finishing work before starting new work.

---

7. Git Integration & Pull Request Linking

All code changes must link to Jira issues.

Recommended branch naming:

PROJ-123-add-payment-retry

Commit message example:

[PROJ-123] Implement retry logic

Benefits:

• automatic linking between code and tickets

• automated workflow updates

• accurate delivery metrics

---

8. Ticket Fields & Data Quality

Keep ticket forms simple.

Required fields:

Summary
Description
Priority
Developer
Assignee
Sprint
Epic Link
Story Points
Labels

Too many fields lead to poor data quality.

---

Story Description Format

Recommended template:

As a [user role]
I want [action]
So that [value]

Example:

As a merchant
I want failed payments retried automatically
So that customers can complete checkout successfully

---

9. Definition of Ready

Stories must meet these criteria before entering a sprint:

• description completed

• acceptance criteria defined

• dependencies identified

• story points estimated

• epic linked

Stories that do not meet these criteria should remain in the backlog.

---

10. Definition of Done

A ticket can move to Done only when:

• Code is merged to main branch

• PR review completed

• Automated tests pass

• QA validation completed (if applicable)

• Documentation updated if required

Example failure case:

PR merged → ticket marked Done → deployment happens days later

This breaks deployment metrics.

---

11. Estimation Best Practices

Use the Fibonacci scale:

1, 2, 3, 5, 8, 13

Guidelines:

Stories larger than 13 points should usually be split.

Exception: if the work is well understood but large.

---

Bug Estimation

Estimate bugs only when they require significant effort.

Do not estimate:

Fix UI typo

Estimate:

Investigate memory leak in payment service

---

12. Backlog Hygiene

Backlogs should remain manageable.

Limit backlog size

Backlog should contain 2–3 sprints worth of ready work.

---

Remove stale tickets

Tickets older than 90 days should be:

Closed as Won't Do
or moved to Ideas backlog

---

Avoid vague tickets

Bad:

Improve performance

Better:

Reduce billing API query latency from 600ms to 200ms

---

13. Sprint Lifecycle

Every sprint follows four phases.

---

Phase 1 - Backlog Refinement

Ensure stories meet the Definition of Ready.

Product owner prioritizes backlog.

Highest value items appear at the top.

---

Phase 2 - Sprint Planning

During planning:

1. review sprint goal

2. estimate capacity

3. select work

4. assign ownership

---

Capacity Planning

Account for non-development time:

meetings
on-call rotations
support tasks
holidays

Recommended planning capacity:

70–80% of theoretical velocity

Example:

Team velocity = 40

Sprint commitment = ~30 points.

---

Sprint Goal Discipline

Each sprint should have one clear goal.

Example:

Good:

Enable credit card payments in checkout

Bad:

Work on multiple improvements

When new work appears mid-sprint, ask:

Does it support the sprint goal?

---

Phase 3 - During the Sprint

Daily standups should focus on:

• blockers

• risks to the sprint goal

• coordination

Bad standup:

Yesterday I coded
Today I will code

Better standup:

What is blocking progress?
What threatens the sprint goal?

---

Pull Request Review Discipline

One of the most common delays in teams is slow code reviews.

Rule:

PR review SLA: 24 hours

Developers should check the Review column first before starting new work.

---

Phase 4 - Closing the Sprint

At the end of the sprint:

1. move unfinished work back to backlog

2. re-evaluate estimates

3. start next sprint

Always click:

Complete Sprint

Leaving sprints open causes reporting errors.

---

14. Incident Handling

Production incidents interrupt normal sprint work.

Incident tickets should:

• bypass sprint planning

• be prioritized immediately

• be resolved regardless of the sprint scope

After resolution, conduct a post-incident review.

---

15. Common Real-World Scenarios

Scope Changes During Development

If requirements change significantly:

Close ticket as Discarded
Create a new ticket

This prevents inflated cycle time metrics.

---

Waiting on Design

If design is missing:

• flag ticket

• tag designer

If the delay exceeds 48 hours, consider moving the ticket back to backlog.

---

External Dependencies

Example:

Waiting on vendor API
Waiting on legal approval

Flag the ticket and document the dependency.

---

Oversized Story Discovered Midway

If a story grows larger than estimated:

Split it into smaller tickets

Large hidden work destabilizes sprint planning.

---

16. Operational Discipline Rules

Ticket Ownership

Teams use a Developer field to identify the primary contributor responsible for implementation.

Guidelines:

• Assignee represents the person currently responsible for the ticket.

• Developer field represents the engineer implementing the work.

---

Story Points

Estimate:

Stories
Tasks
Large Bugs

Do not estimate:

Sub-tasks

---

Ticket Movement Rule

If a ticket has not moved for 2 days, raise it in standup.

It may be blocked.

---

Shadow Work Policy

If work is not in Jira, it did not happen.

Integrate Jira with Git so:

• branches

• commits

• PRs

automatically link to tickets.

---

Final Principle

The purpose of this guide is not process - it is clarity and delivery reliability.

When teams follow these practices:

• work becomes visible

• blockers surface quickly

• planning improves

• engineering metrics remain accurate

Jira then becomes a reliable system for understanding how engineering teams deliver software.