How to write a Jira ticket

A ticket is a contract between Product, Design, Engineering and QA. The format below is the working standard — twelve sections for stories, with adapted variants for bugs and spikes. Every section earns its place; skipping any of them creates predictable downstream cost.

01Title (Summary)

The title should tell a developer what and where without opening the ticket.

Format: [Page/Area] — [What changes] — [For whom if relevant]

Examples Cart — Fix quantity selector not updating total on mobile web
HP — Add personalized product carousel for returning visitors
Login — Error 500 when user submits form with special characters in password

02Ticket type

Use the right type — it drives reporting and velocity tracking.

Story: a user-facing feature or change. Written from the user's perspective.
Bug: something that worked and is now broken, or that doesn't match the accepted specs.
Task: internal/technical work with no direct user-facing impact (refactoring, migration, documentation).
Spike: time-boxed research to answer a question or reduce uncertainty before committing to a story. Must have a clear question and a deadline (never open-ended).
Sub-task: a child of any of the above, used to break work into trackable pieces within a sprint.

03User story (for Stories)

This is not a formality — the so that clause is the most important part. It tells the dev team why this matters, which helps them make the right micro-decisions during implementation.

As a [user segment],
I want to [action],
So that [benefit / outcome].

Example As a returning non-buyer visitor, I want to filter the catalog by price range, so that I can quickly find products within my budget without scrolling through the full catalog.

04Context & background

Two to four sentences explaining why now. What triggered this work? What data supports it? What's the business impact? This section is what separates a PO who understands the business from one who just relays requests.

Example Data shows that 34% of mobile users who add a product to cart abandon at the quantity step. Session recordings reveal that the +/− buttons are too small on screens under 375px, and the cart total does not update until the page is refreshed. This is estimated to cost ~€12K/month in lost conversions based on our sensitivity model.

05Acceptance criteria

The standard format is Given / When / Then (from BDD — Behavior Driven Development). Typically three to eight per ticket. Each one must be independently testable by QA without asking clarifying questions.

GIVEN [a precondition or context]
WHEN  [the user performs an action]
THEN  [the expected outcome]

AC1 — Happy path GIVEN I am on a catalog page with 50+ products
WHEN I set the price filter to min €30 and max €80
THEN only products priced between €30 and €80 are displayed
AND the results count updates immediately
AND the URL updates to include the filter parameters (for shareability)

AC2 — Empty results GIVEN I am on a catalog page
WHEN I set a price range that matches zero products
THEN a "No products found" message is displayed
AND the other active filters remain visible
AND I can clear the price filter to return to unfiltered results

AC3 — Combination with other filters GIVEN I have already applied a color filter (e.g., "red")
WHEN I add a price filter (€30–€80)
THEN results match BOTH filters (red AND €30–€80)
AND both active filters are shown with individual "remove" options

AC4 — Boundary values GIVEN products exist at exactly €30 and exactly €80
WHEN I set the range to min €30, max €80
THEN both boundary products ARE included in results

AC5 — Mobile behavior GIVEN I am on mobile web
WHEN I interact with the price filter
THEN the filter opens in a bottom sheet (not a dropdown)
AND I can confirm or cancel my selection

06Scope

List scope (what this ticket covers — be specific) and out of scope (what this ticket does NOT cover, especially things someone might reasonably assume are included). This prevents scope creep mid-sprint.

Example Out of scope: filter by brand (separate ticket PROD-456), filter persistence across sessions, filter on mobile app (web only for now).

07Design assets

Link to Figma file (specific frame, not the whole project).
All states covered: default, hover, active, disabled, loading, error, empty, success.
Responsive breakpoints: desktop, tablet, mobile.
Long text / short text / edge case mockups.

08Technical notes

This section is optional and written by the dev team during grooming, not by the PO. The PO leaves space for it. It may include:

Proposed technical approach
Known constraints or dependencies
API contracts
Links to relevant code or documentation
Spike findings (if a spike preceded this ticket)

Boundary

The PO describes the what and why. The dev team owns the how.

09Tracking requirements

What analytics events should fire as a result of this feature? Follow the event naming convention.

Event: catalog_filter_applied
Properties:
  - filter_type: "price_range"
  - filter_value_min: [number]
  - filter_value_max: [number]
  - results_count: [integer]
  - filters_active_count: [integer]

10Success metrics

How will we know this worked? Which KPI, which direction, which magnitude, measured after how many days?

Example Success = +5% increase in advance-to-PIP rate from catalog pages on mobile web, measured 14 days post-release on the returning visitors segment.

11Dependencies

Other tickets this one depends on (linked in Jira with is blocked by).
Cross-team dependencies (with owner name and expected delivery date).
External dependencies (third-party API, content delivery, legal approval).

12Metadata (Jira fields)

Standard Jira fields filled at creation: epic link, sprint, fix version, components, labels (including segment, surface, and any escalation tag), priority, story points (set in grooming), assignee, reporter.

13For bugs specifically

Bugs follow a different structure:

Title: [Page/Area] — [What's broken] — [Platform/Browser]
Steps to reproduce: numbered, precise, from a clean starting state
Expected behavior: what should happen
Actual behavior: what happens instead
Environment: browser, device, OS, user segment, URL
Evidence: screenshot, screen recording, console log, error message
Severity: P1 (blocker), P2 (major), P3 (minor), P4 (cosmetic)
Frequency: always reproducible / intermittent / happened once
Regression: was this working before? If yes, since when did it break?

14For spikes

Title: [SPIKE] — [Question to answer]
Context: why we need this research
Question(s): explicit, answerable questions (not "explore X")
Time-box: maximum number of days (usually 1–3)
Expected output: what deliverable is expected (decision doc, proof of concept, technical recommendation)
Expiration: if no conclusion after the time-box, what happens (escalate, kill the idea, extend with approval)

← Back to the process